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A data list is a chain of based variable structures that contain 
data plus pointers that link the structures. List-processing 
techniques are useful for handling data that has logical 
complexities not conveniently represented by conventional 
PL/I array and structure representation. 

Illustrative programs were processed by the PL/I (F) 
Compiler (Version 4) under control of the IBM System/360 
Operating System (Release 16). 

The list-processing facilities of PL/I are an advanced 
topic in programming; this manual is intended for the ex- 
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SIMPL/T has built-in functions to manipulate (insert, © 
delete, etc.) list components. Output from SIMPL/I is 
used as input to the IBM Program Product OS PL/I 
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PL/I Checkout Compiler. 

Manuals that discuss the above-mentioned IBM Program 
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Preface 


The list-processing facilities of PL/I provide more general 
methods of allocating and organizing internal computer 
storage than are available with array and structure organi- 
‘zations. PL/I supplies these facilities through special data 
attributes, built-in functions, interrupt conditions, and 
executable statements, which allow the programmer to 
manipulate storage addresses and to link scattered storage 
areas during the course of program execution. 

Linking scattered storage through address manipulation 
produces a general type of data organization called a /ist, 


and that aspect of programming concerned with organizing | 


and managing lists is referred to as list processing. PL/I, 
however, does not define a specific type of list organiza- 
tion; instead, it allows storage to be linked in an arbitrary 
manner, so that a list can contain any combination of data 
elements, arrays, and structures. This type of organization 
even permits a list to contain other lists as its components. 

The major advantage of lists over conventional array 
and structure organizations is the efficiency they permit in 
the use of storage. A list need reserve only the storage it 
is actually using at any given moment during program exe- 
cution; storage need not lie dormant in anticipation of 
maximum requirements. As additional list components 
are required, their storage is linked to the list and,when 
list components are no longer needed, their storage is 
linked to other lists or reserved in a storage pool for fur- - 
ther use. Such flexibility in storage management also re- 
duces data movementiand frees the programmer from 
having to know exactly how much storage a list will re- 
quire. 

But list processing supplies more than an efficient tech- 
nique for using storage. It also furnishes a method for 
organizing and manipulating data whose structure is not 


Note: Version 4, Release 16 of the PL/I (F) Compiler produced 
the program printouts shown in this manual. 


conveniently represented with PL/I arrays and structures. 
Structured data of this type occurs in many non-numeric 
applications, such as information storage and retrieval, 
system simulation, engineering design, computer-software 
production, text editing, and artificial intelligence. List 
processing preserves the natural structure of the data in- 
volved in such applications and, as a result, avoids unnec- 
essary programming complexity. 

This manual discusses the basic facilities for list pro- 
cessing in PL/I and uses a simple sort application through- 
out the text to show how lists are created and processed; 
printouts of program compilations appear with the dis- 
cussions. The numbering scheme for illustrations asso- 
ciates them with pertinent paragraphs. For example, the 
paragraph numbered IC references figures 1C-1, 1C-2, 
and 1C-3. 

Because the list-processing facilities of PL/I form an ad- 
vanced topic in programming, this manual assumes that the 
reader is an experienced programmer with a knowledge of 
PL/I equivalent at least to that presented in A PL/I Primer, 
Form C28-6808. Familiarity is assumed with array and 
structure organization and with methods for creating and 
invoking subroutines and functions. The programming ex- 
amples in this manual are concerned mainly with illustra- 
ting the use of the list processing facilities and, as a result, 
frequently sacrifice efficient programming techniques for 
the sake of clarity. No references are made to particular 
implementations of PL/I, but information on the F-level 
list-processing facilities appears in JBM System/360: 

PL/I (F) Language Reference Manual (GC28-8201), and 
in JBM System/360 Operating System: PL/I (F) 
Programmer’s Guide (GC28-6594). 


Chapter 1. Introduction 


1A. ADDRESSING STORAGE 


A computer generally uses a serial addressing scheme, 
which permits a series of instructions to be placed in suc- 
cessive storage locations. Similarly, because the data pro- 
cessed by a program is also stored in core, the serial struc- 
ture of core storage is usually imposed upon collections of 
data items that are organized in tabular form. Successive 
data items are then obtained through simple address incre- 
mentation. 

But the simplicity of incremental addressing, as applied 
to data collections, becomes a disadvantage when the 
arrangement of data items within a collection must vary 
during the course of program execution. Such variation 
in data organization frequently occurs in non-numeric 
applications, and produces two major problems: the data 
movement problem, which is concerned with inefficiencies 
in program running time caused by extensive rearrange- 
ments of data, and the storage allocation problem, which 
is caused by excessive allocation of storage in anticipation 
of maximum data requirements. The following discus- 
sions show how both problems have led to the develop- 
ment of list-processing facilities. 


1B. DATA MOVEMENT 


Many computer applications require a collection of data 
items to be arranged in a specific order before processing 
may proceed. Such ordering permits faster retrieval of the 
items than is normally possible with a serial search through 
the unordered collection. The ordering process itself, 


ARRAY: 





Figure 1B-1. Array before insertion of data item 


however, frequently becomes time consuming, particularly 
when conventional sorting methods are used. An exorbi- 
tant inefficiency in processing time may result when sev- 
eral different orderings of the same items occur during the 
running of a program. 

The amount of data that is moved to obtain the desired 
reorderings determines the degree of inefficiency. As an 
example, consider the representation of an array (Figure 
1B-1) which contains four data items arranged in ascending 
sequence. Each item is a string of three characters, and a 
blank item specifies an available position in the array. 
Figure 1B-2 shows the array after the character string 
‘B72’ has been inserted in proper sequence. Three items 
have been moved to provide room for the string inserted 
in the second array position. If the array were larger and 
the items longer, inserting an item could require consider- 
able movement of data. 

One way of avoiding excessive data movement is to per- 
mit collected data items to occupy non-contiguous storage 
locations. A method for such organization is suggested by 
branch instructions, which allow computer control to 
transfer to non-consecutive locations (as required by sub- 
routines and program loops). The location to which con- 
trol is transferred is specified within the branch instruction 
itself. A similar use of storage addresses is possible with 
data items. Each item in an ordered collection can have 
attached to it the address of the next item in sequence, 
then logically successive items need not occupy physically 
contiguous storage locations. 


ITEMS MOVED 
DOWN 





Figure 1B-2. Array after insertion of data item 


Schematic representations of storage addresses are used 
in this manual. A rectangle with a protruding arrow reyfve- 
sents an address element (Figure 1B-3). The arrow indi- 
cates that the rectangle contains an address that “points 
to” another location. When the actual address is not im- 
portant to the discussion, it does not appear within the 
rectangle. An address element that specifies no address 
(that is, a null address) uses no arrow but contains the 
word NULL within the rectangle (Figure 1B-4). Figure 
1B-5 shows an address element attached to a data item, 
and similar use of a null address element appears in Figure 
1B-6. These diagrams provide a means for representing a 
collection of non-contiguous data items. 

Consider Figure 1B-7, which uses an address element at 
the top to point to the first data item in a non-contiguous 
collection. The first data item, in turn, uses an attached 
address to point to the second data item in the collection. 
This process continues until all items are linked. The null 
address attached to the last item indicates the end of the 
collection. 


Figure 1B-3. An address element 





Figure 1B-5. An address element attached to a data item 





Figure 1B-4. A NULL address element 





Figure 1B-6. A NULL address element attached to a data item 


LIST: | 








Figure 1B-7. List before insertion of data item 


The resulting organization shown in Figure 1B-7 forms 
a list, which, for the purposes of this manual, is defined to 
be a collection of non-contiguous data items linked in any 
desired order by means of attached address elements. 
Note that since each data item in a list has an attached 
address element, two data items cannot be physically con- 
tiguous. An address element, however, can be contiguous 
to the data item toward which it points. In general, how- 
ever, an address element is located remotely from the 
data item toward which it points. 

Figure 1B-8 demonstrates how address manipulation 
permits a data item to be inserted into a list. Before in- 
sertion, the list contains four data items which are linked 
in ascending sequence (Figure 1B-7). After insertion, the 
items remain in sequence, but the inserted item ‘B72’ 
occupies the second position in the list. Insertion occurs 
by assigning the address of ‘B72’ to the address element 
attached to ‘A06’ and, in turn, by assigning the address of 
‘C81’ to the address element attached to ‘B72’. Manipu- 
lating addresses in this manner permits list items to re- 
main at their original locations and eliminates the process- 
ing time that would normally be spent in moving the 
items. 


LIST: 





NULL 


Figure 1B-8. List after insertion of data item 


1C. STORAGE ALLOCATION 


In many applications, the amount of storage allocated for 

an array is based on the maximum amount of data that 

might be assigned to the array. Should only a portion of 

the array be needed during a particular run of the program, 

the excess storage reserved for the array will remain un- 

used. Permitting storage to lie dormant in this manner LIST: FREE: 
frequently reduces the effective storage utilization of the | tf 

entire program. 

A major advantage of the list organization shown in 
Figure 1B-8 is that a list requires only the storage it is A06 
actually using at any given moment and does not have to 
reserve additional storage in anticipation of maximum 
requirements. When a data item is inserted into a list, pce || 
only then is the storage for the item linked to the list; 
otherwise, the storage is free to be used elsewhere in the , , 
program. Similarly, when an item is deleted from a list, 
the storage occupied by the item need not remain linked 
to the list; it can be linked to another list or held in a 
storage pool for further use. 

Sharing of storage among lists is conveniently con- 
trolled through a special list that links all storage not cur- 
rently. in use. Consider Figure 1C-1, which contains two 
lists. The first list links four data items, and the second Figure 1C-1. Data list and free-storage list before insertion of new data item 








E98 NULL 


Figure 1C-2. Data list and free-storage list after insertion of new data item 


list contains free storage for three list components. Inser- 
tion of a data item into the first list requires storage to be 
linked to the list. This storage is obtained from the free- 
storage list, as shown in Figure 1C-2 where the item ‘B72’ 
is inserted in proper sequence into the first list. After in- 
sertion, the data list links five items instead of four, and 
the free-storage list contains storage for two list compo- 
nents instead of three. 

Deletion of an item from the data list causes the asso- 
ciated storage component to be linked to the free-storage 
list. Figure 1C-3, for example, shows how the third item 
is deleted from the data list and how the storage for the 
item is linked to the free-storage list. 

This use of a list as a storage pool also frees the pro- 
grammer from having to know precisely how long each 
list in a program may become. Such freedom frequently 
simplifies the design of many computer applications that 
have unpredictable or varying storage requirements. 


1D. THE USES OF LISTS 


The type of list organization presented in the previous dis- 
cussions possesses a simple linear ordering: each data item 
except the first has one predecessor, and each data item 
except the last has one successor. But PL/I does not re- 
strict list organizations to linear orderings; it also allows 
multidimensional orderings, which are obtained by attach- 
ing an arbitrary number of address elements (instead of 
one) to each data item in a list. Additional address ele- 
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Figure 1C-3, Data list and free-storage list after deletion of third data item 


ments permit a list item to be linked to other list items in 
many different directions, so that the ordering within the 
list can be made to reflect the multidimensional ordering 
associated with spatial configurations. With additional 
addresses, it is also possible to link lists in a backward as 
well as a forward direction, and to form circular and inter- 
twined lists. It is even possible for lists themselves to be 
linked together to form higher-level lists. 

The term list processing applies to those programming 
activities concerned with the construction, management, 
and application of list organizations. The computer appli- 
cations that benefit most from list-processing techniques 
generally process large collections of data items that are 
interrelated in a logically complex manner. With lists, it 
is possible to model the logical interrelationships found in 
structured data and to avoid the organizational distortions 
and storage inflexibilities frequently associated with 
arrays. 

List processing simplifies the design of computer appli- 
cations in many areas, particularly those areas concerned 
with the non-numeric aspects of computer programming, 
such as information storage and retrieval, system simula- 
tion, engineering design, computer-software production, 
text editing, and artificial intelligence. These application 
areas are concerned more with the logical structure and 
organization of data and less with numeric computation. 
The following discussions briefly describe the use of list- 
processing techniques in each area. 


1D1. Information Storage and Retrieval 


This application area is concerned with computer tech- 
niques for storing and searching large quantities of infor- 
mation related to specific fields of interest, such as busi- 
ness records, medical histories, government reports, 
statistical indexes, and library catalogs. List processing 
provides efficient methods for inserting, deleting, up- 
dating, and retrieving data in such collections, and allows 
many different orderings and cross references of the 
stored items to be maintained without unnecessary data 
duplication. For example, with list processing, three 
separate copies of a library card catalog, arranged by title, 
author, and subject, can be replaced by a single copy 
within the computer. Attaching three address elements 
to the data content of each card permits simultaneous 
linking of each card to separate lists for title, author, and 
subject. 


1D2. System Simulation 


A system, in general terms, is any collection of elements 
(animate or inanimate) that are united to accomplish a 
specific objective. Examples include traffic control sys- 
tems, manufacturing plants, work routing systems, bio- 
logical organisms, air defense systems, communication 
networks, business enterprises, postal systems, and elec- 
tronic computers. Many large-scale systems cannot be 


studied analytically because their structural complexities 
defy adequate mathematical description. But such systems 
can be modeled or simulated through computer programs 
that operate in a time-sequential manner similar to the 
systems themselves. 

Simulation programs maintain large collections of data 
items that describe the dynamic state of the system at 
particular intervals of time. For example, simulation of a 
traffic control system might require current information 
about the state of all traffic lights, the block-by-block 
traffic on each avenue, and the locations of major traffic 
jams caused by accidents or road repair. List processing 
permits such information to be organized in list form and 
allows the lists to expand and contract dynamically during 
the running of the simulation. 


1D3. Engineering Design 


Engineering structures, such as automobiles, airplanes, 
missiles, machines, bridges, highways, radios, television 
sets, space satellites, and electronic computers, progress | 
through many design stages before an acceptable prototype 
is achieved. Blueprints generally record the design criteria 
at each stage and, therefore, must be redrawn each time 
the design changes. The number of blueprints involved in 
many engineering projects can easily run into the thou- 
sands and, as a result, produce a serious problem in infor- 
mation storage and retrieval. 

List processing provides a convenient way of storing 


blueprint information in machine-processable form so that 
it is easily modified and kept up to date. But the com- 
puting flexibilities associated with list processing also allow 
graphic display devices and automatic drafting boards to 
be incorporated into the design process itself. The cur- 
rent design of an engineering structure, for example, can 
be shown on the scope of a graphic display device where 

it is quickly modified by the design engineer who uses a 
light pen to indicate desired changes. When reflected in 
the current design, such changes can then be used to gen- 
erate a completely new blueprint on an automatic drafting 
board. 

Graphic display devices also permit functional illustra- 
tions of engineering structures to be projected on a scope, 
so that the design engineer can see the structures in opera- 
tion. As an example, the engineer can display a set of 
machine gears on a scope and then make the gears rotate 
under program control. In this way, he can observe how 
the gear teeth mesh and, if necessary, specify changes 
with a light pen. 

Projecting and modifying engineering designs through 
graphic display devices requires flexible methods for repre- 
senting the design within the computer. Such methods 
are available through list-processing techniaues, which not 
only assist in organizing the logical structure of the 
designs but also maintain efficient control over the varying 
storage requirements generated by design changes. 


1D4. Computer-Software Production 


Software systems, such as operating systems, compilers, 
assemblers, generators, subroutine libraries, and industrial 
application packages, frequently exist in multiple versions 
which are designed to run on different inachine configura- 
tions of varying sizes and compositions. Many experi- 
mental techniques are continually being developed to 
automate the production of such software and to elimi- 
nate much of the redundant effort associated with sepa- 
rate implementations. 

One technique that has made significant contributions 
to the automation of software production uses specifica- 
tion languages (meta-syntactic languages) to describe the 
organizational structure of software systems and the hard- 
ware on which they function. Software and hardware 
descriptions made in such languages serve as input to 
special compilers (meta-compilers), which generate the 
desired version of a software system for a specific machine 
configuration. 

A specification language designed for software produc- 
tion generally possesses a free format, is open ended so 
that it can incorporate additional language features, and 
usually employs recursive techniques which permit ex- 
tremely compact descriptions of software and hardware 
characteristics. The descriptions produced in such a lan- 
guage reflect the organizational complexities of the soft- 
ware and hardware being described. The compilers that 


process these descriptions perform intricate analyses to 
generate the desired version of a software system. 

These meta-compilers often use special list organiza- 
tions, called push-down lists or stacks, to simplify the 
scanning and analysis of source descriptions made in 
specification languages. The compilers also rely on list- 
processing methods to maintain efficient control over 
storage requirements, which vary widely, depending upon 
the complexity of the source description under analysis. 


1D5. Text Editing 


The preparation of printed material in the publishing in- 
dustry frequently involves many alterations to the original 
text before final copy is obtained. These changes affect 
copy preparation at all stages; source text undergoes re- 
peated typing, and even after type has been set, modifica- 
tions are still performed, often at great expense. Cheaper, 
quicker, and more flexible methods of producing printed 
text, however, are becoming available with the increased 
use of computers in the printing industry. 

Once source copy is recorded in machine processable 
form (on magnetic tape, for example), it can be modified 
under program control. Text-editing programs can be 
used to insert, delete, and reformat copy, and an output 
tape can also be generated to control the operation of 
automatic typesetting devices, such as linotype and photo- 
composition machines. 

The functions performed by text-editing programs gen- 
erally require extensive movement of data within the 
computer. Characters, words, sentences, lines, paragraphs, 
pages, chapters, and sections are inserted, deleted, modi- 
fied, or shifted to produce the desired text, and the vari- 
able lengths of these textual groupings also affect the 
efficient use of storage. By employing list-processing tech- 
niques, text-editing programs can minimize data move- 
ment and maintain control over storage efficiency. 


1D6. Artificial Intelligence 


This application area deals with computer-related tech- 
niques for supplementing human intelligence. It attempts 
to simulate the cognitive processes involved in such activi- 
ties as game playing (chess, checkers), theorem proving 
(geometry, algebra, symbolic logic), and pattern recogni- 
tion (perception, discrimination, induction, hypothesis 
formulation). 
__ These activities produce extremely complex problems 
which are usually solved in stages. Each stage, however, 
often generates a huge set of subproblems, all of which 
cannot be examined (even on a computer) in a reasonably 
short period of time. In a game of chess, for example, the 
possible lines of play from a given chess position can 
easily involve trillions of moves. But the combinations of 
winning moves continually change as new positions arise 


at each stage of play. Asa result, exhaustive analysis of 
all possible moves in a game of chess is not generally pos- 
sible for a human or a computer. 

Selecting proper subproblems without analyzing all 
possibilities at each stage of problem solution is a major 
concern of artificial intelligence. Short cuts involving 
classification techniques or heuristic methods are needed 
to discriminate among subproblems, and the discovery of 
such short cuts forms the main research activity of arti- 
ficial intelligence. 

Most computer programs designed to mechanize prob- 
lem-solving behavior must contend with varying numbers 
of subproblems and unpredictable variations in problem 
structure. This type of variability calls for flexible meth- 
ods of managing computer storage and organizing the 
structure of a problem. Such methods are available 
through list-processing techniques. 


TE. PURPOSE OF THIS MANUAL 


Detailed development of the application areas described 
in the previous discussions lies beyond the scope of this 
manual. As indicated, however, the various applications 
possess common characteristics that permit efficient use 
of list-processing methods. The purpose of this manual, 


then, is to serve as an introduction to the basic facilities 
for list-processing in PL/I, and to show how these facilities 
form the basis of list-processing methods. The following 
chapters employ variations of an elementary sort program 
to show how lists are created and processed. 





1F. SUMMARY OF CHAPTER 1 


A. A list is a collection of non-contiguous data items | 
linked in any desired order by means of attached ad- 
dress elements. 


B. The term list processing refers to that area of program- 
ming concerned with the construction, management, 
and application of lists. 


C. The use of lists can produce improvements in program 
execution time by avoiding unnecessary data move- 
ment. 


D. The use of lists can also improve overall use of storage 
by maintaining a common storage pool, from which 
storage is obtained when needed and to which storage 
is returned when not needed. 


E. The computer applications that can benefit most from 
list-processing techniques generally process large col- 
lections of data items that are interrelated in a logically 
complex manner. 





Chapter 2. The Organization of Data in PL/I 


Proper understanding of the list-processing facilities in 
PL/I requires a basic knowledge of the internal data orga- 
nizations provided by PL/I, namely, element items, arrays, 
structures, and arrays of structures. This chapter presents 
brief descriptions and simple examples of these organiza- 
tions. The discussion is restricted to those aspects of in- 
ternal data organization that are relevant to the list- 
processing facilities of PL/I. 

List-processing deals primarily with the organization 
and manipulation of data and data addresses within the 
internal storage facilities of a computer. Although it pro- 
vides more flexible methods of handling data than are 
available solely with element items, arrays, structures, and 
arrays of structures, list-processing does not replace these 
data organizations; it builds from them. 


2A. ELEMENT ITEMS 


PL/I statements refer to data items either individually as 
single data elements, or collectively as arrays and struc- 
tures. Single data elements, called element items, have 
arithmetic, string, or label attributes and appear in PL/I 
expressions either as constants or as variables. The follow- 
ing examples show some types of element constants that 
may appear in PL/I programs: 


Element 

Constant Data Type 

751.62 Arithmetic: FIXED DECIMAL (5,2) 
11011.101B Arithmetic: FIXED BINARY (8,3) 
43.8E6 Arithmetic: FLOAT DECIMAL (3) 


111.101E10B Arithmetic: FLOAT BINARY (6) 


‘A1B2C3’ String: CHARACTER (6) 


‘10110111'B String: BIT (8) 


#3INPUT: Label: (the identifier to the left of a colon) 


The DECLARE statement associates attributes with 
element variables as shown in the following examples: 


DECLARE COST FIXED DECIMAL (5,2); 


DECLARE FREQUENCY FLOAT BINARY (21); 
DECLARE TITLE CHARACTER (25); 
DECLARE MASK BIT (6): 

DECLARE SWITCH LABEL; 


In many applications, data items occur in collections 
such as tables and records. To simplify the processing of 
such collections, PL/i provides facilities that allow data 
items to be organized and manipulated in array and struc- 
ture form. 


2B. ARRAYS 


When all the element items in a collection have the same 
attributes, the items can be arranged in a multidimensional, 
tabular form, called an array. Examples of PL/I array 
declarations, with associated serial and spatial representa- 
tions, appear in Figure 2B-1. The serial representations 
indicate how arrays are stored within the computer; note 
that the rightmost subscript values vary most quickly when 
array elements are referred to in succession. 

For serial representation, array dimensions may be inter- 
preted as grouping levels (indicated by the braces in Figure 
2B-1). With this interpretation, a one-dimensional array is 
an array of element items; a two-dimensional array is an 
array of subarrays of element items; a three-dimensional 
array is an array of subarrays of subarrays of element 
items; and so on. The number of element items or sub- 
arrays at a given level is determined by the bounds of the 
dimension for that level. The second declaration in Figure 
2B-1, for example, defines B as an array of three subarrays, 
each of which contains two fixed-point binary values as 
element items. This array has two dimensions. The lower 
bound of the first dimension is 1; the upper bound is 3. 
The second dimension has | as the lower bound and 2 as 
the upper bound. 

Spatial representations of arrays occur in geometrical 
applications and apply to arrays with one, two, or three 
dimensions. These representations frequently simplify the 
definition and analysis of physical problems. Except for 
one-dimensional arrays, however, spatial representations 
have no direct representation within the serial storage of a 
computer. 
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DECLARE A(2) 
FIXED DECIMAL(4); 
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Figure 2B-1. Array declarations with corresponding serial and spatial representations 
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2C. STRUCTURES relative storage requirements for the 13 element items of 


Structures use a system of level numbers to arrange ele- the structure. A structure may contain other structures 


ment items in hierarchical fashion. Unlike array elements, as well as element items. In Figure 2C-2, the major struc- 
however, the elements of a structure need not have the ture TIME CARD contains the minor structures NAME 


same attributes. and DATE. The appearance of the array HOURS in this 


An example of a PL/I structure declaration appears in example also shows that a structure may contain arrays. 


Figure 2C-1. The diagram in Figure 2C-2 represents the A representation of the grouping within this structure is 
given in Figure 2C-3. 


LAST 


DECLARE 


1 TIME CARD, NAME FIRST INITIAL 
2 NAME, MIODLE INITIAL 
3 LAST CHARACTER(15), ANS MAN 
3 FIRST INITIAL CHARACTER(1), oeRsS DEPT = 
3 MIDDLE INITIAL CHARACTER(1), MONTH 
2 MAN# CHARACTER(6), TIME CARD bare bay 
2 DEPT# CHARACTER(4), YEAR 
2 DATE, : HOURS(1) 
3 MONTH FIXED DECIMAL(2), HOURS(?) 
3 DAY FIXED DECIMAL(2), HOURS HOURSI3I 
3 YEAR FIXED DECIMAL (2), HOURSI4) 
2 HOURS(5) FIXED DECIMAL(3,1); HOURSI5) 
Figure 2C-1. Structure declaration for TIME CARD Figure 2C-2. Relative storage requirements for TIME CARD 


MAN NO,DEPT NO DATE HOURS 


First Middle 
an Initial Initial Month} Day | Year |Hours(1) |Hours(2) Hourst3) Hours(4) | Hours(5) 





Figure 2C-3. A time card 


2D. ARRAYS OF STRUCTURES 


PL/I allows a dimension attribute to appear with a struc- 
ture name in a DECLARE statement. This type of decla- 
ration defines an array of structures, which is an array that 
contains structures with identical names and levels. 

Consider the DECLARE statement in Figure 2D-1. 
This declaration defines an array of structures that con- 
tains three array members (see Figure 2D-2). Each array 
member is a structure that contains four element items 
(the high, low, and mean temperature readings for a speci- 
fied date). 


DECLARE 

1 TEMP(3), 
2 DATE CHARACTER(6), 
2 HIGH FIXED DECIMAL(4,1), 
2 LOW FIXED DECIMAL(4,1), 
2 MEAN FIXED DECIMAL(4,1); 


Figure 2D-1. Declaration of an array of structures 


DATE(1) 


} HIGH(1) 


TEMP(1) =< names 
LOW(1) | 
3 MEAN(1) 


TEME TEMP(2) ! 
HIGH(3) 


TEMP(3) 
ain _ 
MEAN(3) 


Figure 2D-2. Relative storage requirements for an array of structures 


DATE(2) | 
HIGH(2) | 
LOW(2) 
MEAN({2) | 


DATE(3) | 





2E. ADVANTAGES OF ARRAYS AND STRUCTURES 


The array and structure facilities of PL/I allow the data 
collections that occur in many different types of applica- 
tions to be represented in a direct, natural way. For ex- 
ample, tax rates, wage scales, time schedules, inventory 
counts, physical measurements, statistical observations, 
frequency distributions, and function values are often re- 
corded and used (even independently of computer appli- 
cations) in formats that closely resemble the array and 
structure organizations of PL/I. By permitting the natural 
organizations of data items to be retained in computer 
applications, the array and structure facilities of PL/I tend 
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to emphasize the application-oriented, rather than the 
machine-oriented, aspects of computer programming. 
This emphasis on the application generally produces great- 
er ease and clarity of programming. 

But arrays and structures do more than simplify the 
writing of programs; they also affect the overall ¢fficiency 
of programs. With these organizations, it is possible to re- 
duce program storage and to improve program execution 
time. For instance, the subscripting and looping facilities 
of arrays often produce more compact programs by 
eliminating redundant statements. Similarly, structures 
avoid time-consuming data scans by providing direct 
access to the subfields of data strings. 


2E1. Reducing Program Size 


The array facilities of PL/I improve program efficiency by 
allowing compact program loops to replace repeated se- 
quences of statements. The significance of the resulting 
reduction in program size becomes evident when attempts 
are made to program without arrays, that is, solely with 
element items. | 

As an illustration, consider the sort procedure SORT 1 
in Figure 2E1-1. This program obtains five successive 
records from the standard system input file (SYSIN), 
sorts the five records into ascending order on the first 
three characters of each record, and puts the five sorted _ 
records into the standard system output file (GSYSPRINT). 
These steps are then repeated until all input records have — 
been processed. (To simplify the discussion, the input file 
is assumed to contain a multiple of five records.) 

A sample printout produced by SORT1 appears in 
Figure 2E1-2; a flowchart of the program is shown in 
Figure 2E1-3. 

An important feature of SORT! is that it does not use 
arrays. Therefore, each of the five records involved in the 
sort has a distinct name: CARD1, CARD2, CARD3, 
CARD4, and CARDS. Treating the records as individual 
elements and not as members of an array increases the 
lengths of the DECLARE, GET, and PUT statements in 
SORT 1 and forces the sort to use four separate IF state- 
ments for successive comparisons of the five records. 

Figure 2E1-4 illustrates successive passes of the sort 
technique used in SORT1. This technique is a type of 
transposition sort. (Note that the efficiency of this tech- 
nique compared to other sort techniques is not under con- 
sideration; the present discussion is preliminary to demon- 
stration of the advantages of arrays.) 

Figure 2E1-5 shows how sorting with an array can re- 
sult in a shorter program. SORT2 produces the same 
results as SORT 1 of Figure 2E1-1. Instead of the five ele- 
ment items CARD1, CARD2, CARD3, CARD4, and 
CARDS, however, SORT2 uses a five-member array named 
CARD. The array name reduces the lengths of the DE- 
CLARE, GET, and PUT statements. (For example, the 
statement GET EDIT (CARD) (A(80)); causes five cards 


SORT1: 


F2EL1_1: INPUT TO SORTI: 
PROCEDURE UPTIUNS (MAIN)3 2 TALE UF TH------~--------- - - = = + 5 
DECLARF A96_SECUND-~--~------------- tcasobopeaes 9 
(CARUL, CARD2, CARD3, CARD4, CARS, ALG_FIRST---—--------------------------- 1 
ee ET Ai btsieree ne ceneireintenioent 
CLUSE FILE (SYSPRINT)3 aaa aa ea aa : 
eae NUTPUT FRUM SORTL: 
Bie: ALlG_FIRST-------------- ~--------------- 1 
GET A96_ SE CUND- ~- ~~ - 9 2 nr nn ee nn ee 2 
ENTT (CAKDL, CARDA, CARD3, CAKING, FO02_THIRU-----~-----~----------+-------- 3 
CARDS) (A(80))3 W17_FUURTH-~--------------------------- fy 
ol, PTT FP Hees ee eee eee s 
SKIP (2) LIST (C8 INPUT TM SORTIE°DG 
arr INPUT TU SORT: 
(CARL 4 CARD2» CARD3, CARDS, CARDS) Be el 
(SKIP, ALROI)5 oe 
Sapte E02_THIRD------------~---~-------------3 
Re Gs Wl 7_FUURTH---- ------~---- -- -- + - - ------% 
[+ |e eS a hata ll Sta} 
SUBSTR (CAROL, 1-3) >SUCSTRICARD2 4143) 
THEN OUTPUT FROM SORTIL: 
DOs : Al4_FIRSI-------------------- -- +--+] 
cK = A oe ‘ GARDL:3 CARDL = CARD25 A96_ SECOND Rg Ae Saeco eee eee ea 
sy Sang st ees F02_THIRD~--~------------~-------------3 
= Wi 7_FUURTH-------------~~--~--- - - - + - == = 4 
SUASTRICARD2 5193) >SUSSTRICARU3 9193) a aa a a aaa a a a 9 
THEN 
WO; INPUT TO SORT: | 
K = 13 SAVE = CARD23 CARN2 = CARD35 WT FOURTH ses Se SSeSe ee ese ee Se ~--% 
CARD3 = SAVE; 271 _f€ IF TH--~------------- ites lee aes Satin ae leas 
FND; A96_SECOND--------------------------+--=2 
i | 414_FIRST---------~---------- ~-+--+----] 
SUBSTR (CARD 3914 3)>SUBSTRICARD4 9153) Pao Tee ee es 
THEN = 
mre | NUTPUT FRUM SORTL: 
K = L3 SAVE = CARD3; CARD3 = CARU4; : i | 
CARDS = SAVES ALeeP RS eal See ia. 
ENL; AI96_ St COND=<—=S42=s=-=S2s3 4 s+—S>e> ere 
IF FO2_THIRU~-----------------------------3 
SUBSTRICARD4s, 1532) >SUXSTR(ICARD 5, 1+ 3) wil 7 FOUR TH------------ oe ne nn re ee ~& 
THEN TTA_F IF YH-----------------~------------ 5 
NGs 
K = 13 SAVE = CARD4: CARDS = CARDS; 
END: | Core eee Figure 2E1-2. Sample printout produced by SORT1 
IF 
K = | 
THEN 
CO 10 
SORT; 
Put 
SKIP (2) LIST (*OUTPUT FROM SORT1=°); 
Put 
EDIT 
(CARD1, CARD2, CARD3, CARD4, CARDS) 
(SKIP, A(80))3 
GO TO 
INPUT$ 
OVER: 
END 
SORTL3 


Figure 2E1-1. Sorting without an array 
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SAVE = CARD2 
CARD1 = CARD2 CARD2 = CARD3 
CARD2 = SAVE CARD3 = SAVE 


Figure 2E1-3. Flowchart for procedure SORT] 


SAVE = CARD3 
CARD3 = CARD4 
CARD4 = SAVE 


SAVE = CARD4 
CARD4 = CARD5 
CARDS5 = SAVE 


‘SAVE = CARD1 














NOTE: 


KEYi = SUBSTR(CARDi,1,3) 
(where i= 1,2,... ,5) 





to be read). The array name also allows a single IF state- 
ment within a DO loop to replace the four IF statements 


used in SORT1 for comparing successive records. 


Besides being a shorter program, SORT2 is more easily 
modified than SORT1. A change in the number of records 
to be sorted by SORT2 requires adjustments only in the 
size of the array CARD and in the upper limit of the DO 
statement. Corresponding modifications in SORT1 would 
require changes in the number of record names used by 
the DECLARE, GET, and PUT statements, as well as a 
change in the number of IF statemenfs used for comparing . 


successive records. 


The flowchart for SORT2 appears in Figure 2E1-6. 
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Figure 2E1-4. Example of sorting by: successive interchanges 
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SORT2: 
F2E1_5: 
PRUCEDURE UPTIONS 
DECLARC 
(CARD(5), 
UN ENDFILE 


(MATIN) $ 


60 TO OVERS 
END$ 
INPUT: 
GET 


SORT: 


ENIT (CARD) (CA0C8G)I)DS 


COMPARE: 
DO I = 1 TO 43 


IF 


SAVE) CHARACTFR(?70)3 
(SYSIN) BEGINS 
CLUSE FILE (SYSPRINT); 


SUASTRICAKROCT) 6163)-> SUBSTRICA2L 


(Il *# Ll)» le 3) 
THEN 
DU; 


OAK 


= ls SAVE = 
ARD(I + 1)3 
tN); 
tNb 
COMPARE $ 
IF 
K = |] 
THEN 
69 TN 
SORT? 
PUT - 
SKIP (2) CLIST 
PUT 
SKIP (2) 
PUT 
SKIPS 
GE Tm 
INPUTS 
OVER: 
END 
SORT25 


OUTPUT FROM SORT2: 





A%6.. SECOND ————— sss 2 
DVN. FIP Terese as 


OUTPUT FROM SORT2: 


BAA (hs Pere ly 
€02_THIRD--~-----——----—— eee 
WE 7 FOUR i sg 


OUTPUT FROM SORT2: 








96 _SECON0———-——---—---—-__-- 2 
z 7 Le | FT Omen tne ee ee een enen aren dn Ab an een a ene ae § 


Figure 2E1-5. Sorting with an array 


CARDCT)$ 
CARD(I + 


CARH(T) = 


1) 


C*CuUTPUT FROM 


SAVES 


SCRT23*)3 


EOIT (CARD) (& (RO), SKIPS 


13 


START 


GET 5 
CARDS 





‘ 


YES YES 
K=1 
NO ? 


NO NO 


NO PRINT 
SORTED 
CARDS 


CARD(I+1) = SAVE NOTE: 


Figure 2E1-6. Flowchart for procedure SORT2 _ 
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KEY(!) = SUBSTR(CARD(1),1,3) 
(where | = 1,2,... ,4) 


2E2. Avoiding Data Scanning 


An improvement can be made to the SORT2 program 
of Figure 2E1-5 by not using the built-in function 
SUBSTR, which obtains the first three characters of each 
record. Although SUBSTR is a useful function for ob- 
taining a portion of a string, the function is time-consum- 
ing and should be avoided when reduction in program 
execution time is desired. 

One way of removing SUBSTR from the SORT2 pro- 
gram is to declare the explicit structure of each element in 
the array CARD. Then the first three characters of each 
element can be referred to directly by name rather than 
indirectly through SUBSTR. 


The SORT3 program in Figure 2E2-1 contains explicit 
structure declarations for the members of CARD. The 
first three characters in each member of CARD are named 
KEY and the remaining 77 are named DATA. This decla- 
ration of an array of structures permits SORT3 to avoid 
references to the built-in function SUBSTR and, as a re- 
sult, produces a shorter execution time for SORT3 than 
for SORT2. In general, explicit declarations improve data- 
access time and thereby provide faster execution time. 


2F. SUMMARY OF CHAPTER 2 


A. PL/I statements refer to data items either individually 
as element items or collectively as arrays, structures, 
or arrays of structures. 


B. Array and structure facilities permit the natural orga- 
nizations of data items to be retained, and thus tend to 
emphasize the application-oriented rather than the 
machine-oriented aspects of computer programming. 


C. The use of arrays can shorten programs by eliminating 
redundant statements. 


D. The use of structures can avoid time-consuming data 
scans by providing direct access to the subfields of 
data strings. 


SORT3: 
F2E2_1: 
PROCEDURE OPTIONS (MAIN)D3 
DECLARE 
1 CARO(5), 
2 (KEY CHARACTER(3), 
DATA CHARACTER(77)), 
1 SAVE, 
2 (KEY CHARACTER(3), 
DATA CHARACTER(77))3 
ON ENDFILE (SYSIN) BEGIN; 
CLOSE FILE (SYSPRINT)3 
GO TU OVER; 
END; 


_ INPUT: 


GET 
EDIT (CARD) (A(3),— A(77))3 
SORT: 
K = 03 
COMPARE: 
DO 
I= 1 TO 43 
LF 
CARD.KEY(I) > CARD. KEY(I + 1) 
THEN 
OU$ 
K = 13 SAVE = CARD(I)3$ 
CARD(I) = CARD(I ¢ 1); 
CARD(I + 1) = SAVES 
END; 
END 
COMPARES 
IF 
K = 1 
THEN 
GO TO 
SORT 3 
PuT 
SKIP (2) LIST (*OUTPUT FROM SORT3:*)3$ 
OUTPUT: ; 
DO 
I = 1 TO 593 
PuT 
SKIP EDIT (CAROD(I))0A03)_5 AI77))3 
END 
OUTPUTs$ 
PuT 
SKIP(2)3$ 
GO TO 
INPUTS 
OVER: 
END 
SORT33 


OUTPUT FROM SORT3: 

AL4_F IRS V2 == 
A96_SECOND- enn 2 
E02_THIRO-----——-~----------- 3 
Wi 7_FOURTH-—---——--—-—---—-- === 4 
271 _F LE TH-———————— $= 5 





OUTPUT FROM SORT3: 


Al4_FIRST---————----—------—--—----—-- 1 
271_F1FTH-—-—--—--—-—- s 


OUTPUT FROM SORT3: 


Al4_FIRST--—-----——--——-——----- -———- ---——-1 
£02_THIRO——--—------———_—_---—--_—-—-3 
wit, _FOURTH-——-——-—- = ---- 4 
271_F 1FTH---~---—--~-- -- = -- 5 


Figure 2E2-1. Sorting with an array of structures 
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Chapter 3. Techniques for Addressing Data 


The previous chapter showed how array and structure 
organizations permit reductions in program size and im- 
provements in data-access time. These efficiencies, how- 
ever, are diminished ¢n many programs by the additional 
execution time that results from extensive movements of 
data within the computer. For example, the three sort 
programs SORT1, SORT2, and SORT3 of the previous 
chapter move entire records when interchanges occur. 
This practice causes a large amount of data to be moved 
and, as a result, produces a slow sort. Execution time is 
affected not only by the number of records being sorted 
but also by the size of each record.: Generally, the less 
data that has to be moved, the faster the sort. 

This chapter shows how data movement can be reduced 
by manipulating the addresses of data items rather than 
the items themselves, and also shows how scattered data 
items may be organized into collective units without mov- 
ing or duplicating the items. 


3A. TYPES OF ADDRESSES 


A data address, as used in computer programming, speci- 
fies a particular storage location within which data can be 
stored and from which it can be retrieved. PL/I provides 
three major types of data addresses: symbolic, relative, 
and absolute. Brief explanations of each type appear in 
the following discussions. 


3B. SYMBOLIC ADDRESSES 


A symbolic address is an identifier that appears in a source 
program in place of an actual storage address (which, in 
machine language, is generally represented by a numeral). 
In PL/I, a symbolic address consists of a sequence of 
alphameric and break characters, the first of which must 
be alphabetic. 

Symbolic addresses free the programmer from having 
to keep track of specific storage locations, simplify pro- 
gram organization and modification, and allow mnemonic 


names (such as TAX, PAYROLL, DATE1, and MASTER _ 


FILE) to be associated with data items. When a source 
program is translated into machine language, the compiler 
associates each symbolic address with a specific storage 
location. The ability to form such associations distin- 
guishes symbolic programming from numeric coding. 
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3C. RELATIVE ADDRESSES 


As demonstrated by the SORT 1 program of Figure 2E1-1, 
programming solely with element items generally results in 
large programs, because distinct names are needed for each 
item. Organizing element items into arrays, however, re- 
duces the number of distinct names in a program, permits 
address modification through changes in subscript values, 
and usually produces compact programs. 

A reference to an item in an array consists of the array 
name followed by a subscript expression that specifies the 
position of the item in the array. In such a reference, the 
array name is a symbolic address, but the subscript ex- 
pression is a relative address, because it specifies the loca- 
tion of the item relative to the beginning of the array. 

Alteration of subscript values provides a restricted form 
of address modification that may be used to reduce data 
movement during execution of a program. When used for 
this purpose, subscript values may be stored in auxilliary 
arrays or employed as element links within arrays. Illustra- 
tions of these methods are given in paragraphs 3C1 and 
3C2. 


3C1. The Use of Subscript Values in Auxilliary Arrays 


The SORT4 program in Figure 3C1-1 shows how a second 
array N may be used to reduce data movement in a sort of 
an array of structures named CARD. SORT4 processes 
the same input and produces the same results as SORT1, 
SORT2, and SORT3 in the preceding chapter. After 
assigning input data to the five structures of CARD, 
SORT4 then assigns the integers 1 through 5 (in fixed- 
point binary form) to the five successive positions of N. 
Each element of N is treated as a subscript value that spe- 
cifies (points to) one of the structures in CARD (see 
Figure 3C1-2). 

As SORT4 compares the fields named KEY in succes- 
sive structures of CARD, necessary interchanges are per- 
formed not on the structures of CARD but on the values 
of the corresponding elements of N. Moving the element 
values of N, rather than the 80-character structures of 
CARD, causes less data to be moved. 

At the completion of the sort, the structures of CARD 
remain in their original (physical) order, but the element 
values of N are rearranged. Taken in succession, the re- 
arranged values of N specify the sorted structures of 
CARD in ascending order on their KEY fields (see Figure 


3C1-3). 


As indicated in Figure 3C 1-4, successive structures in 


_ the sorted array CARD may be referred to by the expres- 


sions CARD(N(1)), CARD(N(2)), CARD(N(3)), 


SORT4: 
F3C1l_1: 
PROCEDURE OPTIONS (MAIN)$ 
DECLARE 
N(5) FIXED BINARY(3), 
1 CARD(5)>, 
2 (KEY CHARACTER(3), 
DATA CHARACTER(77))3 
ON ENDFILE (SYSIN) BEGINS 
CLOSE FILE (SYSPRINT2S 
GO TO OVER; 
END; 
INPUT: 
GET: 
EDI T( CARD) (A(3) 5 ACTT))DS 
INITIALS 
DO 
I =1 TO 5s NII) = I 
END 
INITIALS 
SORT: 
K = 03 
COMPARE : 
DU 
I = 1 TO 43 
IF 
KEYVY(N(T)P>KEVINGI ¢ 1)) 
THEN 
DO; | 
N(OIT)$ NOI) = NOT # 178 
J3 


K =13$ J 
NCI + 1) 


END; 
END 
COMPARE; 
IF 
K =,1 
THEN 
GO TO 
SORT$ 
PUT | 
SKIP (2) LIST (*OUTPUT FROM SORT4:*)3 
OUTPUT: 
DO 
I = 1 TO 53 
PUT 
SKIP EDIT (CARD(N(1T)))0A(03),A077))3 
END 
OUTPUT; 
PUT 
SKIP(2)3 
GO TO 
INPUTS3 
OVER: 
END 
SORT4$ 


OUTPUT FROM SORT4: 
AlL4_F IRST—---------——------------------- l 
A96_SECOND-~---------~-—~-~---------- --—2 
£02_THIRD--------------~----------~----- 3 
Wi ?_FOURTH----~-------------------------- 4 
LTL_FIFIH----------------------—-—----- 5 


OUTPUT FROM SORT4: 


Al4_FIRS1--------------------—--------- 1 
A96_SECOND-----~--~--—-----------—----- 2 
E02_THIRD-~---~-—------------—--------- 3 
W17_FOURTH--~-------------—------------ & 
LT1_F IF TH-~-—--—-------------- —---—----- 5 


OUTPUT FROM SORT4: 


Al4_FIRST-----------------—----------—- 1 


A96_SECOND------~-—--~—-----------————--2 
E02_THIRD----------------~-------------3 
W17_FOURTH------~-~-----~---------—---- 4 
271_F If TH------------------------------5 


Figure 3C1-1. Using an auxilliary array of subscript values to 
reduce data movement in a sort 
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Figure 3C1-2. Auxiliary array and array of structures before sort 
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Figure 3C1-3. Auxiliary array and array of structures after sort 
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Figure 3C1-4. Sequential references to the sorted elements in an 
array of structures 
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CARD(N(4)), and CARD(N(5)). The compactness of 
these expressions shows the advantages of using sub- 
scripted subscripts when the elements of one array specify 
the elements of another array. 

Although the structures in CARD appear only once, 
SORT4 specifies two orderings of CARD: the original 
(physical) order and the sorted (logical) order. With addi- 
tional arrays of subscript values, it is possible to obtain 
further orderings from a single copy of CARD. This use 
of auxilliary arrays, then, not only reduces data movement 
but also avoids data duplication. Similar benefits may be 
obtained from auxilliary arrays when array elements are 
gathered, scattered, inserted, deleted, or merged. 


3C2. Using Subscript Values to Link Array Elements 


Subscript values can be used also to link (chain) the ele- 
ments of an array into an ordered sequence. One way of 
doing this appears in the SORTS program of Figure 3C2-1, 
which processes the same type of input data and produces 
the same type of output as SORT4. 


SORTS: 
F3C2_1:3 
PROCEDURE OPTIONS (MAIN)3$ 
DECLARE 
1 CHAIN, 
2.H FIXED BINARY (3), 
2 €(5), 
3 CARD, 
4 KEY CHARACTER (3), 
4 DATA CHARACTER (77), 
3 L FIXED BIMARY (3)3 
ON ENDFILE (SYSIN) BEGIN; 
CLOSF FILE (SYSPRINT)3$ . 
GO TO OVER; 
END; 
INPUT: 
GET 
EDIT (CARD) (A03),A(77))3 
INITIALS 
H = 13 
Ll) = 23 L(2) = 33 L(3) = 43 
L(4) = 55 L(5) = 03 
SORT: 
K_TEST = O3 
IF 
KEY(H) > KEY(L(H)) 
THEN 
00; 
K_TEST = 13 J_SAVE = L(H)3 
N_USAVE = L(J_SAVE)3 
L(J_SAVE) = Hs L(H) = N_SAVES 
H = J_SAVE; 
END; 
I = H$3 
DO 
WHILE (L(L(I)) we O)3 
IF 
KEY (L(I)) > KEY(LOIL(T))) 
THEN 
DO; 
KUTEST = 13 JUSAVE = LIL(I))s: 
' NUSAVE = L(J_SAVE)$ 
L(J_SAVE) = LCI) 
L(L(IT)) =N_SAVES 
L(I) = JUSAVE3: 
END; 


Because the methods used in SORTS are more complex 
than those used in the previous program (SORT4), the 
need for SORTS might be questioned, particularly since 
both programs achieve the same results with equivalent 
efficiency. The main purpose for developing SORTS, 
however, is not to improve SORT4 but to introduce 
(through the already familiar methods of subscripting) the 
linkage techniques that underlie all list-processing meth- 
ods. As later discussions show, the chained sequence of 
CARD structures used by SORTS forms a type of primi- 
tive list organization. 

SORTS uses an array of structures called CHAIN, 
which contains an element item H and an array of struc- 
tures E. Each of the five structures in E consists of a 
minor structure CARD and an element item L. 

The program begins by assigning input data to the five 
structures named CARD (which are members of the array 
named E), and then assigns the integers 1 through 5 (in 
fixed-point binary form) to the element H and the first 
four L elements; the fifth element L receives a value of 
zero. 


END; 
IF 
K_TEST = 1 
THEN 
GO TO 
SORT$ 
PUT 
SKIP (2) LIST (*OUTPUT FROM SORTS:*); 
PUT 
SKIP; 
I = H3 
DO 


WHILE (I -= Q)3 


SKIP EDIT (CARD (1)) (AQ3), AC77))3 
I= cls 


ENDS 
PUT 
SKIP (2)3 
GO TO 
INPUTS 
OVER: 
END 
SORTS3 


OUTPUT FROM SORTS: 


A14_F IRS T= nn 
A96_SECOND-—--~----—--——-——-—-------—_--.2 
£02_THIRD-----——--—-—--—-—_---- —__-__--_-- 3 
W17_FOURTH----~----—-—----—-- ---------—4 
271 LF TH----——--——--—--- 5 





OUTPUT FROM SORTS: 





AL4_F IRS T——---——-—-—-—---—---——-- 1 
A96_ SECOND === === == = 2 
E02_THIROD——-----——-——-——--—-- -—---—---- 3 
W17_FOURTH---------—-—-—----------_-_--4 
271_F LF TH-———-——-—-——-—_----- 5 


OUTPUT FROM SORTS? 








Figure 3C2-1. Using subscript values as element links to reduce data movement in a sort of an array of structure 
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As illustrated in Figure 3C2-2, element H acts as a head- 


er for CHAIN; that is, its value (in this case, 1) serves as a 
subscript item that specifies (points to) the first CARD 


structure (namely, CARD (1)). The value of element L(1), 


which is associated with CARD(1), specifies the subscript 
of the second CARD structure (namely, CARD (2)), and 
so on, until all CARD structures in CHAIN have been 
linked. The zero value of the last L element indicates the 
end of CHAIN. 

SORTS compares the KEY fields of successive CARD 
structures. Required interchanges are performed on the 
values of the H and L elements rather than on the CARD 
structures themselves; as a result, little dat4 is moved dur- 
ing the sort. At the completion of the sort, as shown in 
Figure 3C2-3, the CARD structures remain in their origi- 
nal (physical) order, but the values of the H and L ele- 
ments (underlined in the figure) link the structures in 
ascending order on their KEY fields. 


The steps in Figure 3C2-4 show how SORTS uses the 
following statements to transpose the order of the first 
two CARD structures: 


J_ SAVE = L(H); 
N_SAVE =L(J_ SAVE); 
L(J_ SAVE) = H; 

L(H) = N_ SAVE; 

H=J_ SAVE: 


The variables J SAVE and N_ SAVE (both declared by 
default) serve as work variables for saving intermediate re- 
sults. Also note that the interchange of the two CARD 
structures CARD(1) and CARD(2) requires modification 
of three link values: H = 2; L(1) = 3; and L(2) = 1;. 

Step 4 of Figure 3C2-4 shows how the CARD struc- 
tures are linked after the first interchange has been com- 
pleted. At that point in the sort, the CARD structures 
occur in the following order: 


CARD(2), CARD(1), CARD(3), CARD(4), CARD(5) 


This is the logical order in which the CARD structures are 


linked; their original physical order remains unchanged. 
When an interchange does not involve the first (logi- 


cally first) CARD structure in the sorted sequence, header 
H is not modified; and, as the steps of Figure 3C2-5 show, 


SORTS uses a different set of instructions for the inter- 
change: 


I=H; 

J_SAVE = L{L(1)); 
N_SAVE=L{J_SAVE); 
L(J_ SAVE) = L(1); 
L(L{(I)) = N_SAVE; 

Lil) = J_SAVE: 


CHAIN 


‘CHAIN 


Figure 3C2-2. 
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Figure 3C2-3. Array of linked structures after sort 
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Step 1 J_SAVE = L(H); N_SAVE = L(J_SAVE); 







Peeve [ BATA _ 


| KEY (4) DATA (4) 






Step 3 L(H) = N_SAVE;: 
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Step 4 H = J_SAVE; 
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Figure 3C2-4. Perforthing the first interchange, which involves CARD(1) and CARD(2) 
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Step 3 L(L(I)) = N_SAVE; 
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|=H; J_SAVE = L(L(1)); NLSAVE = L(J_SAVE); 
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Step 4 L(l) = J_SAVE; 





Figure 3C2-5. Performing the second interchange, which involves CARD(1) and CARD(3) 
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Figure 3C2-6. Sequential references to the sorted elements in a linked array of structures 
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Figure 3C2-7. Flowchart for procedure SORTS 


Since SORTS executes these instructions under control of 
a DO-loop, variable I is used to specify successive CARD 
structures in the chained sequence; header H is not used 
for this purpose, because its value must be retained to 
determine which structure occurs first in the sequence. 
Note the use of subscripted subscripts in Figure 3C2-5. 
Expression L(L(I)) in Step 1, for example, refers to the 
link value of CARD(1), since I= 2 and L(1) = 1. The 
figure illustrates the effect of the second interchange, 
which involves CARD(1) and CARD(3). Step 4 shows the 
CARD structures linked in the following order after the 
interchange has been completed: | 


CARD(2), CARD(3), CARD(1), CARD(4), CARD(5) 





LAST 
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CARD: 1 = Lit) 


A complete sort of the CARD structures links them in 
the following order: 


CARD(3), CARD(2), CARD(5), CARD(4), CARD(1) 


Figure 3C2-6 shows how the sorted CARD structures may 
be referred to in succession by the expressions: CARD(H), 
CARD(L(H))}, CARD(L(L(H))), CARD(L(L(L(H)))), and 
CARD(L(L(L(L(H))))). The compactness of these expres- 
sions illustrates the advantages of using successive levels of 
subscripted subscripts. 

A flowchart for SORTS appears in Figure 3C2-7. 


yx 


3D. ABSOLUTE ADDRESSES 


The addressing techniques used in the two previous ex- 
amples (SORT4 and SORTS) depend upon relative ad- 
dresses (subscripted array names). This dependency upon 
subscripts prevents similar applications of address manipu- 
lation to data items that are not contained in arrays. Fur- 
thermore, subscripting increases the time it takes the 
machine-language version of the program to refer to an 
element of an array. At execution time, the program must 
calculate the actual address of the array element in core 


storage and use this address in place of the relative address. 


3D1. The Relationship of Relative 
and Absolute Addresses 


As an illustration of the relationship between relative ad- 
dresses and actual addresses, consider the array of struc- 
tures CARD shown in Figure 3D1-1. Each structure in the 
array is identified by a subscripted array name: CARD(1), 
CARD(2), CARD(3), CARD(4), and CARD(5). The same 
array appears in Figure 3D1-2, but the subscripted array 
name for each structure has been replaced by a possible 


storage address. It is assumed that each structure occupies 


80 addressable storage positions and that the firsi struc- 


ture begins at location 1000. Then the structures have the . 


successive addresses 1000, 1080, 1160, 1240, and 1320. 
For convenience, the addresses are specified in decimal 
notation and not in binary, as would be required in the 
machine code for IBM System/360. 

These addresses are called absolute addresses, because 
they specify the actual locations of the structures in stor- 
age. An absolute address is never relative to any location 
other than the first position of storage. By contrast, a 
relative address can be relative to any location in storage 
and, consequently, must be converted to an absolute ad- 
dress before it can be used by the program at execution 
time. Although the program automatically performs the 
conversion from relative to absolute form, such conver- 
sions may add to the running time of the program. 

' PL/I does not provide a direct means for controlling 
the absolute address of a data item. It is the operating 
system that determines which storage areas are available 
to a program at execution time. However, once a specific 
storage location has been allocated for a data item, PL/I - 
makes it possible to obtain the absolute address of the 
location and to assign the absolute address to a special 
type of variable called a pointer variable. 

Pointer variables can be organized into arrays and used 
in a manner similar to the way subscripts were used in 
SORT4 and SORTS. But pointer variables provide advan- 
tages over subscripts: they eliminate the need for storing 
data items in arrays and thereby avoid the time spent in 
converting relative addresses to absolute form. The fol- 
lowing discussions presant the rules for manipulating | 
pointer variables and illustrate their use with examples. 
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Figure 3D1-1. An array of structures showing a relative address 
(subscripted array name) for each structure 
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Figure 3D1-2. An array of structures showing a possible absolute 
address for each structure 
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3D2. Pointer Variables 


Pointer variables have absolute addresses as their values. 
Declaration of an identifier with the POINTER attribute 
establishes the identifier as a pointer variable. 


EXAMPLES: 


DECLARE P POINTER; 
DECLARE (Q, R) POINTER EXTERNAL STATIC; 
DECLARE T(5) POINTER INTERNAL, V(—2:2, 
~3:3)POINTER; 
DECLARE 1A, 

2X CHARACTER(15), 

2Y POINTER; 


_ DECLARE 1 TABLES, 


2 1(5) POINTER, 
2 J(0:4) POINTER; 


As shown in these examples, PL/I allows pointer vari- 
ables to be individual element variables or elements of 
arrays and structures. A pointer variable can have any 
storage class and scope, and the usual default rules for 
these attribute types also hold for a pointer variable. 


3D2A. How to Obtain a Value for a Pointer Variable 


Before a pointer variable can be manipulated, it must be 
assigned an absoluie address. One way of obtaining an ab- 
solute address is to use the built-in functions ADDR and 
NULL. A reference to the built-in function ADDR has the 
following form: 


ADDR(argument-variable) 


The value returned by ADDR is the absolute address of 
the specified argument variable. As an example, consider 
the following assignment statement: 


P= ADDR(X); 


Assume P is a pointer variable and X is a data variable. 
Then the reference ADDR(X) obtains the absolute address 
of the storage location allocated for X, and the statement 
assigns this absolute address as the value of pointer P. 


The argument variable in a reference to ADDR must be 
an identifier that specifies one of the following types of 
variables: 


. an element variable 

an array 

an element of an array 

. a major Or minor structure 
an element of a structure 


moom> 


The argument can be of any data type and storage class, 
but special results occur when the following conditions 
apply to the argument of ADDR: 


AA. When the argument is a controlled variable, the value 
of the ADDR reference specifies the absolute ad- 
dress of the current generation of the argument. If 
no storage has been allocated for the controlled 
argument, ADDR specifies a null address (which in- 
dicates unallocated storage). 


BB. When the argument is a parameter of a containing 
procedure, the value of the reference to ADDR repre- 
sents the absolute address of the argument associ- 
ated with the parameter (including the absolute ad- 
dress of a dummy associated argument). 


CC. When the argument is an array expression that speci- 
fies two or more noncontiguous elements, a refer- 
ence to ADDR is not valid. For example, the ele- 
ments of an array cross-section whose reference 


includes asterisks not in the rightmost position or 
positions do not occupy contiguous storage loca- 
tions. Since ADDR obtains a single absolute ad- 
dress, it has no way of relating noncontiguous 
storage positions with that address. 


A reference to the built-in function NULL uses no argu- 
ments and has the following form: 


NULL 
This function returns a nui: address value that does not 
identify any location in storage. As later discussions illus- 
trate, this special address value is used to clear pointer 


variables and to test for unallocated storage. 


3D2B. Using Pointer Variables in Assignment Statements 


' PL/I permits pointer variables to appear in the following 


forms of the assignment statement: 
1. element-pointer-variable = element-pointer- 
expression; 
2. pointer-array = element-pointer-expression; 
3. pointer-array = pointer-array; 


Two or more variables separated by commas may appear 
on the left side of these statements for multiple assign- 
ment. An element-pointer expression on the right side of 
an assignment statement must be either an element-pointer 
variable or a function reference (built-in or programmer- 
defined) that specifies an element pointer value, that is, a 
single absolute address. 

Assignment of an element-pointer expression to a point- 
er array causes the value of the expression to be assigned 
to every element of the pointer array. When a pointer 
array appears on the right side of an assignment statement, 
the number of dimensions and the bounds for each dimen- 
sion of the array on the right must be identical to those of 
the receiving pointer array on the left. 


EXAMPLES: 


Assume the following pointer declarations: 


DECLARE(P,Q,R,T(5), V(—2:2, —3:3)) POINTER; 
DECLARE 1 A, 2 X CHARACTER(15), 2Y POINTER; 
DECLARE 1 TABLES, 2 1(5) POINTER, 2 J(0:4) 
POINTER; 


The following statements illustrate possible pointer assign- 
ments: 

. P= ADDR(A); 

Q,R=NULL; 

. T(4), V2, —3) =P; 

A. Y = T(4); 

. TABLES. I, TABLES. J = NULL; 

. T= TABLES. I; 


25 


Statements 2, 3, and 5 perform multiple assignments. The 
last three statements show name qualification applied to 
pointer variables. 


3D2C. Using Pointer Variables in Operational 
Expressions 


PL/I allows only two operators to use pointer variables as 
operands: the comparison operators equal (=) and not 
equal (1=). A major consequence of this restriction is 
that arithmetic operations cannot be performed on abso- 
lute addresses. 


EXAMPLES: 


Assume that A and B are arithmetic variables and that P, 
Q, R, S, and T are pointer variables; then the following 
statements contain permissible uses of pointer variables as 
operands: 

1. IF P= NULL THEN GO TO L; 

2. A=(Q7=R); 

3. IF (T=NULL) | (T=ADDR(B)) & (S_ =NULL)) © 

THEN P=Q; | 7 


The last example shows that simple comparisons of point- 


er variables may be compounded. 


3D3. Based Variables 


Although the value of a pointer variable represents the ab- 
solute address of a specified data item, the pointer itself 
provides no information about the attributes of the data 
item. Such descriptive information is needed, however, for 
proper manipulation of the data item at execution time. 
For example, a pointer variable can specify the absolute 
address of an array A, but neither the pointer name nor 
the pointer value indicates the dimensions of A or the 
characteristics of its elements. 

To associate descriptive information with a pointer 
variable, PL/I provides a special type of variable called the 
based variable, which is declared with the following attri- 
bute: 


BASED(element-pointer-variable) 


The element-pointer variable appearing in the BASED 
attribute cannot be a based variable itself nor can it be 
subscripted. 

Declaration of a based variable does not assign an ad- 
dress to the pointer variable specified in the associated 
BASED attribute. Before reference can be made to a 
based variable, an address must be assigned to its associ- 
ated pointer variable. 

Any reference to a based variable applies the attributes 
of the based variabie to the storage location specified by 
the associated pointer variable. Consider the following 
declaration: | 
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DECLARE NAME CHARACTER(15) BASED(P); 


This statement declares the 15-position character string 
called NAME to be a based variable and associates the 
pointer variable P with NAME. A subsequent reference to 
NAME will then cause the location given by P to be 
treated as a storage area for a 15-position character string. 
For example, let NAME appear in the following assign- 
ment statement: 


NAME = ‘JOHN’; 


This statement assigns the character-string constant 
‘JOHN’ to a 15-position storage area at the location given 
by P. The four characters of the constant are positioned 
to the left in the area and are followed by eleven blank 
characters. 

The attribute BASED(element-pointer-variable) is de- 
fined to be a storage-class attribute along with STATIC, 
AUTOMATIC, and CONTROLLED. The appearance of 
BASED in a DECLARE statement, however, does not pro- 
duce an allocation of storage. Only when an absolute ad- 
dress is assigned to the pointer variable related to the 
based variable does storage become associated with the 
based variable. For example, consider the previous declar- 
ation of the based variable NAME. Not until an absolute 
address is assigned to pointer P does storage become asso- 
ciated with NAME. When this association occurs, NAME 
is said to be “based on” P. 

The value of the pointer variable in a BASED attribute 
can specify a location of any data type and storage class, 
including POINTER data and BASED storage. Care must 
be taken, though, when changing the pointer value related 
to a based variable to assure compatibility between the 
attributes of the based variable and the data at its newly 
assigned location. 


3D3A. Assigning Pointer Values with the Set Option 


Executing an assignment statement is not the only way of 
assigning an address to a pointer variable. Another way is 
to use a SET option with one of the following statements: 


READ FILE (file-name) SET (element-pointer-variable); 
LOCATE based-variable FILE (file-name) SET (element- | 
pointer-variable); 

ALLOCATE based-variable SET (element-pointer- 
variable); 


The READ and LOCATE statements perform record- 
oriented transmission; they process sequential buffered- 
files and allow logical records to be retrieved from and 


_ stored in file buffers. The ALLOCATE statement allocates 


storage for a based variable and assigns the location of the 
allocated storage to the pointer variable specified in the 


SET option. Further discussion of the ALLOCATE state- 
ment appears in paragraph 4B1. The following discussion 
presents brief explanations of the SET option in READ 
and LOCATE statements. 

The READ statement obtains the location of the next 
logical record in a buffer associated with the specified 
file, and assigns the lecation to the element-pointer vari- 
able given in the SEToption. A based variable associated 
with the same pointer will then relate to the fields of the 
logical record. The based variable is effectively overlaid 
on the logical record in the buffer. 

The LOCATE statement allocates the next available 
storage area for the specified based variable within a buf- 
fer associated with the file. The location of the allocated 
storage is assigned to the element-pointer variable given 
in the SET option. The LOCATE statement need not con- 
tain a SET option; when it does not, an implied SET is 
assumed, which uses the pointer variable in the BASED 
attribute of the specified based variable. 

Record-oriented transmission statements may read and 
write the values of pointer variables. A pointer value that 
has been written, however, cannot be assumed to locate 
the same data if it is read back into storage (further dis- 
cussion of this appears in Chapter 5). Under no circum- 
stances may pointer values be read or written with stream- 
oriented transmission statements. 


3D3B. Using a Based Variable in a Function Procedure 


Function procedure MEAN in Figure 3D3B-1 shows how 
a based variable can be used with an array of pointers to 
simulate a variable-length parameter list. This function 
procedure uses one parameter P, which is an array of 
pointers. The single asterisk in the dimension attribute of 
P indicates that P is one dimensional and has the sare 
dimension bounds as its associated argument in an invoca- 
tion of MEAN. This use of the asterisk notation allows 
the function to process pointer-array arguments of dif- 
ferent sizes. 

Since the elements of P are associated with pointer 
values and the number of its elements can vary, P acts as 
a variable-length parameter list. Variability can also be 
achieved by associating a null pointer value with one of 
the P elements. 

MEAN assumes that the non-null pointer values in P 
specify the locations of fixed point decimal values. The 
function computes the average of these arithmetic values 
and, as indicated by the attributes in the PROCEDURE 
statement, returns the average as a fixed-point decimal 
value. 

Assignment of each non-null pointer value in P to 
pointer S causes the attributes of based variable VALUE 
to be applied to the locations specified in P. When all 
elements in P are null, the function returns a zero value. 


T_MEAN? 
F3D3B_1: 
PROCEDURE OPTIONS (MAIN); 
DECLARE 
MEAN RETURNS (FIXED), 
(TOCLOD, X) FIXED (5), 
(P(10), S) POINTER; 
Put 
PAGE LIST (*INPUT ARRAY T IS: *)3 
#1D0: 
00 
I = LBOUND (1-1) TO HBOUND (1,1); 
GET 
EDIT ¢(Tt(l)) 
PUT SKIP DATA (¢ 
TCT): 
P(I) = ADORCT(I)): 


(F(5))5. 


END 
#1003 
. PUT SKIP (2)3 
X = MEAN (P)3 
Put 
SKIP (3) LIST 
(*RESULT RETURNED BY PROC **ME ANE? =*, X)3 
MEAN: 
PROCEDURE 
(P) FIXED (5)3 
DECLARE 
(P(*), S) POINTER, 
VALUE BASED (S) FIXED (5), 
(Mp N) FIXED (5)3 


M, N = O$ 
LOOP: 
DO 
I = LBOUND (P,1) TO HBOUND (P,1);3 
F 
P(I) -= NULL 
THEN. 
DO; 
S = P(I)3 
M= M + VALUE3 
N=N # 13 
END; 
ENO 
LOOP; 
IF 
N = 0 
THEN 
RETURN (0); 
ELSE 
RETURN (M/N)3 
END 
MEANS; 
END T_MEANS 


INPUT ARRAY ¥ IS: 
TO1L)= 11; 
T(2)= 225 


T(3)= 333 
T(4)= 44; 
T(5S)= 553 
T(6)= 66; 
T(7)= TT; 
T(B8)= 88; 
T(9)= 995 
TC LOD= Lls 


RESULT RETURNED BY PROC *MEAN® = 50 


Figure 3D3B-1. Using a based variable and an array of pointers to 
simulate a variable-length parameter list 
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The lower and upper bounds of the array argument 
associated with parametet P are determined by the built- 
in functions LBOUND and HBOUND, reference to which 
occurs in the DO statement of MEAN. 


3E. ARRAYS AND STRUCTURES OF BASED 
VARIABLES 


Besides being used in the declarations of element items, 
the BASED attribute can also appear in the declaration of 
an array, a structure, or an array of structures. When ap- 
plied to a structure or an array of structures, BASED 
must appear at level 1 and, consequently, applies to all 
_members of the structure or array of structures. 

Care is also required when assigning an absolute address 
to the pointer variable of a based array or structure to 
assure that the address actually specifies the location of an 
array or a structure. For example, it is generally incorrect 
to assume that the address of an array or a structure is 

‘the same as the address of its first element. Compilers 
frequently place descriptive information, applicable to the 
entire array or structure, before the first element of the 
array or structure in the object program. This descriptive 
information can cause the address of the complete array or 
structure to differ from that of the first element when the 
program is executed. | 

As an example, consider the following sequence of 
statements: 


DECLARE 
TABLE(5) FIXED DECIMAL(2), 
1 CARD, 

2 KEY CHARACTER(3), 

2 DATA CHARACTER(77), 
(P,Q,R,S) POINTER: 


P = ADDR(TABLE); 
Q = ADDR(TABLE(1)); 


R = ADDR(CARD); 
S = ADDR(CARD.KEY); 


It cannot be assumed in this example that pointers P and 
Q have the same address value; the address of TABLE is 
not necessarily equal to the address of its first element 
TABLE(1). The same distinction applies to pointers R and 
S; the address of structure CARD generally differs from 
the address of its first element CARD.KEY. 
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When a component of a based structure is referred to, 
the address of the component, relative to the beginning of 
the structure, is automatically accounted for and need not 
be adjusted (offset) by the programmer. Consider the 
following statement sequence: 


DECLARE P POINTER 
1 I BASED(P), 2 J CHARACTER(10), 2 K CHARAC- 
TER(20), 
1 L, 2M CHARACTER(10), 2 N CHARACTER(20); 


GET EDIT (MN) (A(10), A(20)): 
P = ADDR(L): 
PUT LIST(K); 


In this example, values for element variables M and N in 
structure L are obtained from the standard system-input 
file (SYSIN) by the edit-directed GET statement. Assign- 
ment of the address of L to pointer P associates the de- 
scription of the based structure I with the storage of 


structure L. The reference to K in the list-directed PUT 
statement causes the value of N to be printed. Note that 
no adjustment in the address of structure L assigned to 
pointer P is necessary to obtain the value of N, even. 
though N is the last element in the structure. 


3E1. Qualifying Based Variables with Pointer Variables 


PL/I allows a based variable to be associated with more 
than one storage area at the same time. This multiple 
association is possible because a based variable by itself 
does not specify a data item, but only a description of 
storage. A based variable specifies the attributes and ex- 
tent of the storage with which it is associated. But a 
change in the value of the pointer variable specified in the 
declaration of the based variable causes the based variable 
to become associated with different storage, and conse- 
quently, with new data. It is the combination of pointer 
variable and based variable, therefore, that determines the 
location and description of a data item. 

So far, the BASED attribute is the only facility that 
has been presented for associating a pointer variable with 
a based variable. Since only one pointer variable can ap- 
pear in a BASED attribute, some other facility is required 
for simultaneously associating two or more pointers with 
the same based variable. The PL/I facility that permits 
this multiple association is called pointer qualification. It 
is used to distinguish among two or more storage areas 
associated with the same based variable, and allows other 
pointers to override the pointer that was specified in the 
declaration of the based variable. 


The pointer qualification symbol is a composite symbol 
that resembles an arrow. It consists of a minus sign imme- 
diately followed by a greater-than symbol (—>). This 
composite symbol, however, does not signify an operation; 
its function is similar to that of the period symbol used in 
the qualified name of a structure element. When used, 
the pointer qualification symbol must always appear be- 
tween two references. The reference on the left must be 
either an element-pointer variable or a reference to the 
built-in function ADDR. When it is an element-pointer 
variable, it cannot be subscripted nor can it be of the 
based storage class. The reference on the right of the 
pointer qualification symbol must be a based variable. 

A pointer qualification symbol applies the storage 
description of the based variabie on its right to the storage 
location specified by the pointer value on its left; the 
pointer originally declared with the based variable is over- 
ridden. As an example, consider the following assignment 
statement: 


A—>B = C—>B; 


Assume B is a based variable, and A and C are nonbased, 
element-pointer variables. The expression C—>B refers to 


a data item that has the attributes declared for B and the 
location specified by C. Similarly, the expression A—>B 
determines the location and attributes of the area to 
which the data item is assigned. Thus, the pointer quali- 
fication symbols used in this assignment statement associ- 
ate the attributes declared for the based variable B with 
the two distinct storage areas addressed by pointers A and 
C. This association constitutes pointer qualification. 

The examples of pointer qualification given below use 
the variables described in the following DECLARE state- 
ment: 


DECLARE 
(P,Q) POINTER, 
1 W BASED(P), 
2 X FIXED, 
2 Y FLOAT, 
2 Z POINTER, 
(A, B BASED(Q)) FIXED; 


P and Q are pointer variables. W is a based structure, and 
X, Y, Z are based element-variables within W. Observe 
that Z is a based element-pointer variable. A is a non- 
based fixed-point variable, and B is a based fixed-point 
variable. 

Assume that P and Q have been assigned absolute ad- 
dresses; then the following statements contain valid refer- 
ences to the elements of the based structure W: 


A. Y=X; 
B. P—>Y = P—>x; 


In statement A, the references to the based elements 

X and Y do not involve the pointer qualification symbol; 
therefore, the pointer variable P given in the BASED 
attribute of W implicitly specifies the location of the 
structure addressed by P within which the attributes of X 
and Y are to be applied. If desired, explicit qualification 
of X and Y by P can be specified, as shown in the second 
statement. Statements A and B are effectively equivalent. 


C. Q—>Y = Q->x; 


Statement C shows that a different pointer, in this 
case Q, can be used to override pointer P, which appears 
in the based declaration of W. 


D. P—>Y =Q—>Y; 
E. Q—>X = P—>x; 


The references in statements D and E show that two 
different pointers may qualify the same based variable at 
the same time. This is the multiple association of storage 
areas with a based variable, as discussed previously. In 


statement D, the attributes of element Y are applied 
simultaneously to the two different structure locations 
given by P and Q. Similarly, statement E applies the attri- 
butes of element X to the structure locations given by P 
and Q. 


F. Y=(Q—>X)+(Q—>Y); 
G. P->Y = (Q—>X) + (Q—>Y): 


Statements F and G are equivalent. They add the 
values of elements X and Y within the structure location 
addressed by Q, and assign the sum to element Y within 
the structure given by P. Statement G contains explicit 
pointer qualification of the receiving based variable; 
statement F does not. 


H. Q—>W=W; 


Assignment of a based structure occurs in statement H. 
Structure W at location P (implicit) is assigned to structure 
W at the location specified by Q (explicit). 


1. ADDR (A)—>B = X; 
J. Y= ADDR (A)—>B; 


Statements I and J use references to the built-in func- 
tion ADDR to qualify references to the based element B. 
In each case, ADDR (A) returns a pointer value that 
qualifies B. Note that statement J, unlike statement I, 
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involves conversion of the assigned value from FIXED 
type to FLOAT type. 


K. Q—>Z=P; 
L. Z=Q; 


Pointer assignment occurs in statements K and L. P 
and Q are each pointers, and Z is a based pointer. Pointer 
Q in statement K explicitly qualifies based pointer Z, 
which receives the value of pointer P. In statement L, 
pointer Z receives the value of pointer Q, but Z is a based 
pointer, which is implicitly qualified by pointer P. State- 
ment L is equivalent to P—>Z = Q). 


M. Q—>W.Y = Q-—>W.X; 


Statement M shows pointer qualification used with 
name qualification. Q overrides pointer P, which was 
declared with based structure W. This statement also 
involves conversion of the assigned value from FIXED 
type to FLOAT type. 


SE2, Pointer Qualification in a Subroutine 


subroutine procedure SWAP in Figure 3E2-1 contains an 
example of pointer qualification used to interchange the 
values of nairs of variables. When invoked, the subroutine 
associates parameter P with a one-dimensional pointer 
array of even, but arbitrary, length. Each pointer value in 
P specifies the location of a fixed-point integer of length 
8, and SWAP interchanges the numbers at successive 

pairs of locations. The interchange of individual pairs of 
values resembles that done in the previous sort routines, 
except that SWAP does not perform sorting. 

The subroutine associates the based variable CARD 
with each location specified in P. However, since each 
interchange involves two locations, the subroutine must 
associate CARD with two different locations at the same 
time. This double association is achieved by qualifying 
CARD with separate pointers, S and R, as shown in the 
following statements: 


SAVE = S—>CARD; 
S—>CARD = R—>CARD; 
R—>CARD = SAVE; 


The first location of each pair of locations is assigned to 
pointer S, the second to pointer R. 

The number of locations specified in array parameter 
P is determined by the built-in functions LBOUND and 
HBOUND. 

The illustrations in Figure 3E2-2 show how SWAP 
processes four character strings. 
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TEST_SWAP: 

F3E2_13 

PROCEDURE OPTIONS (MAIND$ 

DECLARE 
P(LO) POINTER, 
T(10) FIXED (8)3 
J = LBOUND (T,1)3 
K = HBOUND (T,1)3 


PAGE LIST (* INPUT ARRAY T ISs °)3 


I = J TO K3 
T 


EDIT (TCID) CFC8IDS 
PuT 
SKIP DATA (TC1))3 
P(T) = ADOR(ITCIDDS 
END 
#100; ° 
CALL SWAP (P)3 
PUT : : 
SKIP (3) LIST 
(*RESULT OF PROCEDURE **SWAP*?*:¢)3 


#200: 
00 
I = J TO K3 
PuT 
SKIP DATA (TOT))3 
END 
#2003 
SWAP: . 
PROCEDURE (P)5 
DECLARE ° 
(P(*), Re S) POINTER, 
(CARD BASED (S), SAVE) FIXED (8)5 
tL = LBOUND (P,1)3 
M = HBOUND (P,1)3 
LOOP: 
DO 
I =t TO M-—1 BY 23 
R = P(I41)3 
S = P(I)$ ° 
SAVE = S->CARD; 
S->CARD = R=->CARD$ 
R=>CARD = SAVES 
END 
LOOP; 
RETURNS 
END 
SWAP ; 
END 
TEST_SwAaP; 


TNPUT ARRAY T IS: 
TOL)s= 12345673 
T{2) 89012345; 
T(3)= 678901233 
T(4) 456789013 
T¢5)2 23456789; 
TU6)= 1234567; 
T(T)= 89012345; 
T(8)= 678901233 
T(9)= 45678901; 
TCO) = 23456789; 


RESULT OF PROCEOURE °SWAP®: 
TOLh)= 890123453 


 T2)d= 12345673 


103) 45678901; 
TU4)2 67890123; 
TC5)s 12345673 
Tl6)= 23456789; 
T(7)= 678901233 
T(8)= 890123453 
T(9)® 23456789; 
T(10)= 45678901; 


Figure 3E2-1. Using pointer qualification in a subroutine 
procedure 


A « ADDR(A) S 


P(1) ADDR(A) 
P(2) ADDR(B) (80)’X’ B ADDR(B) R 


P(3) ADDR(C) 
(g0)'Y' ¢ 





P(4) ADDR(D) 


(BEFORE SWAPPING) 


LOOP: DO =L BOUND (P,1) TOH BOUND (P,1) — 1 BY 2: 
R=P(I+ 1);S=P(l); 
SAVE = S—>CARD; 


S —> CARD = R —>CARD; 


_ R—>CARD = SAVE; 
END Loop; 





(80) ‘xX’ A 


P(1) ADDR(A) 


P(2) ADDR(B) 


P(3) ADDR(C) 


CC eS ADDR(C) S 
P(4) ADDR(D) 


w 


(80)‘Y’ D : ADDR(D) R 


(AFTER SWAPPING) 


Figure 3E2-2. How pointer qualification is used by subroutine procedure SWAP in Figure 3E2-2. 
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3E3. Restrictions on Based Variables 


The following restrictions apply to based variables: 


A. The EXTERNAL attribute cannot appear in the declar- 


ation of a based variable, but a based variable can be 
qualified by an external pointer variable. 


B. Based variables cannot have the INITIAL attribute, 
nor can arrays of based labels ‘be initialized by sub- 
scripted label prefixes. 


C. Data-directed input and output cannot transmit the 
value of a based variable. 


D. The BASED attribute cannot be specified for the 
parameters of subroutines or functions. 


E. The CHECK ON-condition cannot be applied to a 
based variable. 


F. The VARYING attribute cannot be applied to a based 
variable. 


3E4. Contextual Declarations of Pointer Variables 


The appearance of an identifier in one of the following 
contexts serves as a contextual declaration of the identi- 
fier as a pointer variable: 


A. in a BASED attribute 

B. in the SET option of READ, LOCATE, and ALLO- 
CATE statements 

C. on the left of a pointer qualification symbol (—>). 


A contextually declared pointer variable receives the 
AUTOMATIC storage class and INTERNAL scope by 
default. If different attributes are desired, they must ap- 
pear in an explicit declaration of the pointer variable, that 
is, along with the POINTER attribute. The pointer vari- 
able contextually declared with a based variable does not 
receive the null pointer value as a result of the based dec- 
laration. 

Only the INITIAL CALL form of the INITIAL attri- 
bute is allowed in explicit declarations of pointers. 


3F. ADVANTAGES OF ABSOLUTE ADDRESSING 


The absolute addressing facilities provided by pointer and 
based variables permit the same reductions in data move- 
ment that were obtained earlier in this chapter by using 
subscript values as the relative addresses of array elements. 
The following discussions present examples that show 
how pointer variables and based variables, in addition to 
reducing data movement among array elements, also per- 
mit efficient organization and manipulation of scattered 
data items. 
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3F 14. Reducing Data Movement 


Procedure SORT4 showed how an auxiliary array of sub- 
script values may be used to reduce data movement in a 
sort. The same sorting efficiency can be obtained by using 
pointer values in place of subscript values. Unlike the 
subscript values in SORT4 however, pointer values need 
not be members of an auxiliary array. The same sort 
technique can use individual pointer elements as well as 
pointer arrays. Examples of both methods appear in the 
following discussions. 


3F2. Sorting with Pointer Variables 


Procedure SORT6 in Figure 3F2-1 sorts the same input 
data processed by the previous sort examples. After 
assigning input data to the five structures in the array of 
structures called CARD, SORT6 assigns the absolute ad- 
dresses of the structures CARD(1), CARD(2), CARD(3), 
CARD(4), and CARD(5) to the element pointers P1, P2, 
P3,P4, and P5. Since the based structure IMAGE has the 
same structuring and attributes as the structures in CARD, 
IMAGE may be used with appropriate pointer qualifica- 
tion to refer to the components of CARD. 

SORT6 compares the KEY subfields in the successive 
structures of CARD; necessary interchanges are performed 
not on the structures of CARD but on the address values 
of the corresponding pointers P1 through PS. Moving 
pointer values rather than 80-character structures causes 
less data to be moved and produces a faster sort. 

At the completion of the sort, the structures of CARD 
remain in their original (physical) order, but-the values of 
pointers P1 through P5 are generally changed. Taken in 
succession, the pointers specify the sorted structures of 
CARD in ascending order on their KEY fields (see Figures 
3F2-2 and 3F2-3). As indicated in Figure 3F 2-4, succes- 
sive structures in the sorted array CARD may be referred 
to by the expressions P1—>IMAGE, P2—>IMAGE, 
P3—>IMAGE, P4—>IMAGE, and PS—>IMAGE. 


3F3. Sorting with an Array of Pointer Variables 


A more compact version of the previous example, SORT6, 
can be obtained by replacing the five element pointers P1 
through PS with a five-element array of pointers. Proce- 
dure SORT7 in Figure 3F3-1 shows how such an array, 
P, can be used to obtain the same resuits as SORT. 
Because DO loops can be used to modify references to 
the pointer elements of array P, SORT7 requires fewer 
statements than SORT6. Care must be taken, however, 
when using the based structure IMAGE in references to 
the coniponents of the array of structures CARD. A 
reference to IMAGE cannot be qualified by a subscripted 
pointer variable. Therefore, SORT7 uses the element 
pointers S and T to qualify usages of IMAGE. Then any 
element of array P that is to qualify IMAGE must have its 


value assigned to pointer S or pointer T, which performs 
the actual qualification. Except for their use of a pointer 
array, the diagrams associated with SORT7 (Figures 
3F3-2, -3, and -4) are identical to those associated with 
SORTS. 


SORT6: 
F3F2_1: 
PROCEDURE OPTIONS (MAIN)D$ 
DECLARE 
(Pl, P2y P3_ P4, P5) POINTER, 
1 IMAGE BASED(S), 
2 KEY CHARACTER(3), 
2 DATA CHARACTER(77), 
1 CARD(5), 
2 KEY CHARACTER(3), 
2 DATA CHARACTER(77)3 
ON ENDFILE (SYSIN) BEGIN; 
CLOSE FILE (SYSPRINT)3$ 
GO TU OVER; 
END 
INPUT: 
GET 
EDITICARD) (A03), ALTT))$ 
P) = ADDR(CARD(1))3 
P2 = ADDRICARD(2))3 
P3 = ADDR(ICARN(3))3 
P&4 = ADDRICARD(4))$ 
P5 = ADDR(CARD(5))3 
SORT: 
K = 05 
IF 
{(PL—->IMAGE.KEY) > (P2—>IMAGE-KEY) 
THEN 
DU3 
K = 13; S = Pls Pl = P23 P2 = S3 
END; 
IF 
(P2—>IMAGE.KEY) > (P3—->IMAGE.KEY) 
THEN 
DU; 
K = 13 S = P23 P2 = P33 P3 = S35 
END$ 
IF 
(P3—->IMAGE.KEY) > (P4—->IMAGE.KEY) 
THEN 
DO; 
K = 13 S = P33 P3 = P43; P4 = S3 
END; 
IF 
(P4->IMAGE.KEY) > (P5—>IMAGE.KEY) 
THEN 
DU; 
K = 13 S = P43 P4 = P53 P5 = S3 
END3 
IF 
K = } 
THEN 
GO TO 
SORT; 
PuT . 
EDIT (PL-~>IMAGE,P2->IMAGE, 
P3->I MAGE, P4->IMAGF, 
P5—>IMAGE) (SKIP, A383), AVCTT))3 
PuT | 
SKIP3 
Go TU 
INPUT 3 
OVER: 
END 
SORT6$ 


Figure 3F 2-1. Using pointers to sort an array of structures | 
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Vigure 302-2, Pointer variables and array of structures before sort 
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Figure 3F 2-3. Pointer variables and array of structures after sort 
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P1 —> IMAGE CARDIT 
| FIFTH 
| KEvi2)! DATA(2) 
P2 —> IMAGE r CARDI(2} 
| SECOND | 
| DATA(3) | 
P3 —> IMAGE ae CARG(3) CARD 
{ FIRST 
| DATA(4) 
P4 —> IMAGE amare CARD(4) 
| FOURTH | 
DATA(S) 
P5 —> IMAGE , CARDI(S) 


Figure 3F 2-4. Sequential references to the sorted elements in an 


array of structures 


SORT7: 
F3F3_13 
PROCEDURE OPTIONS (MAIN)$ 
DECLARE 
(P (5), T) POINTER, 

IMAGE BASED(S), 
KEY CHARACTER(3), 
DATA CHARACTER(77), 
CARD(5), 

KEY CHARACTER(3), 
DNATA CHARACTER(77)3 
ON ENDFILE (SYSIN) BEGINS 
CLOSE FILE (SYSPRINT)3 
GO TO OVER; 

ENDS 


Th) MN) m= AY RO 


INPUTS 
GET 
EDITI(ICARD) (A3) 6 AI77))3 
DO 


I 1 TO 53 P(T) = ADDRICARD(T)); 


END; 
SORT: 


LOOP: 
DO 
I 
S 


1.70 43 
P(I)s T = PUT + 1)5 


IF | 
(S->IMAGE.KEY) > (T->IMAGE.KEY) 
THEN 
DO; 
K = 13 P(T) = Ts PUT + 1) = S3 
END; on 
END 


I 
S 
PuT 
END 
OUTPUTs$ 
PuT 
SKIP$ 
GO TO 
INPUT$ 
OVER: 
END 
SORT73 


Figure 3F3-1. Using an array of pointers to sort an array of 
structures 
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EDIT (S->IMAGE) (SKIP, A(3), AI77)73 


P(1) 


P(2) 


P(3) 


P(4) 


" p(s) 


P(1) 


P(2) 


P(3) 


P(4) 


P(5) 


oomieanow 


ADDRICARD(2)) 


| ADDRI(CARD(3)) 


ADODRICARD(4)) 


ADORICARD(S5)) 





ADDRICARD(1)) 





/\ 


N 


Fie 


KEY(2)1 DATA(2) 
4 CARD(2) 
DATA) | anoia) CARD 


! 


KEV(5)| DATA(S) | canpis) 
i 


Figure 3F3-2. Array of pointers and array of structures before sort 
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CARD(2) 


CARD(3) ) CARO 


CARD(4) 








\e FOURTH 
\E (5) DATA(S5) 
tee! 








CARD(5) 





Figure 3F 3-3. Array of pointers and array of structures after sort 
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an [rem 
4 KEY(2) DATA(2) 
\ KE Y(3) OATA(3) 


fe Foun 
KEY(8) DATAIS) 


coe 


S = Ptr); S —> IMAGE CARDI1) 






S$ = P(2); S -> IMAGE CARD(2) 


S$ = P(3); S —-> IMAGE CARD(3) CARD 









[\ CARDI4) 


S = Pia); S —> IMAGE 







S = P(6); S —> IMAGE CARD(5) 





HIGH 


Figure 3F3-4. Sequential references to the sorted elements in an 


array of structures 


3G. ASSOCIATING DATA ITEMS IN SCATTERED 
LOCATIONS 


The two preceding procedures, SORT6 and SORT7, re- 
quire the data items involved in a sort to be placed in an 
array of structures before sorting actually occurs. There 
is no need, however, for the items to be placed in such an 
array. Once the absolute address of each item is assigned 
to a position in the pointer array, the location of one 
data item relative to another has no effect upon the effi- 
ciency of the sort; scattered (noncontiguous) data items 
are sorted with the same efficiency as those contained in 
arrays, because only addresses are moved. 


Either an array of pointers or a pointer variable at- 
tached to each item can be used to associate scattered data 
items with each other. Examples of both methods appear 
in the following discussions. 


3G1. Associating Data Items through an Array of 
Pointer Variables 


Procedure SORTS in Figure 3G1-1 uses an array of pointer 
variables to sort sets of structures that are not contained 
in an array. The procedure assigns the absolute addresses 
of the individual structures:to the element positions in the 
array of pointers. At this stage, SORT8 becomes identical 
to SORT7 and produces the same results. This equiva- 
lence is possible because the relative locations of the 
structures (whether members of an array or not) have no 
effect upon the actual sorting operations. 

The major difference between the two procedures is 
that SORT8 requires more statements than SORT7. These 
additional statements result from having to declare each 


SORTS: 
F3G1_13 
PROCEDURE OPTIONS (MAIN)D$ 
DECLARE 

(P(5), T) POINTER, 
IMAGE BASED(S), 
KEY CHARACTER(3), 
DATA CHARACTER(77), 
CARDI,— 
KEY CHARACTER(3) >» 
DATA CHARACTER(T7T7), 
CARD2, 
KEY CHARACTER(3), 
DATA CHARACTER(77), 
CARD3, 
KEY CHARACTER(3), 
DATA CHARACTER(77), 
CARD4G, 
KEY CHARACTER( 3), 
DATA CHARACTER(77), 
CARDS, 
KEY CHARACTER( 3), 
DATA CHARACTER(77)35 
ON ENDFILE (SYSIN) BEGINS 
CLOSE FILE (SYSPRINT)$ 
GO TO OVERS 


™ NM m= §— 1% m ROR ew DDR om 8 AD ASN 


END: 
INPUT: 
GET 
EDI T(CARD1, CARD2, CARD3, CARD4, 
CARDS) 
(A(C3),5 ACTT))3 
P(l) = ADDR(CARD1I);$ 
P(2) = ADDRI(CARD2); 
P(3) = ADDRI(CARD3) 3 
P(4) = ADOR(CARD4S)$ 
P(5) = ADDRICARDS) >; 
SORT: 
K = 03 
LOOP: 
DO 
I = 1 TO 43 
§S = P(I): T = PCI + 103 
IF 
(S->IMAGE.KEY) > (T-—>IMAGE.KEY) 
THEN 
DO; 
K = 13 PCI) = Ts PCT + 1) = S3 
END; 
END 
LOOP $ 
IF 
K = 1 
THEN 
GO TO 
SORT; 
OUTPUT: 
DO 
I = 1 TO 53 
S = P(I)D3 
PUT 
EDIT (S—>IMAGE) (A(3), AL77))3 
PUT 
SKIP; 
END 
OUTPUT 3 
PUT 
SKIP S$ 
GO TO 
INPUTS | 
OVER: 
END 
SORTS83 


Figure 3G1-1. Using an array of pointers to sort structures not 
in an array 
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structure separately and also from having to use separate 
. e . 

assignment statements to assign the absolute addresses of 

the structures to the array of pointers. The increase in 








program size is usually offset by a decrease in execution P(t) | ADDRICARDS) f reev | bata] 
time, since data items are referred to more directly when : oy oa a) ens 
not in an array. P(2) | ADDRI(CARD2) | | 
Except for their use of scattered structures, the dia- 
grams associated with SORT8 (Figures 3G1-2, -3, and -4) SU elan: Ha SnRieRaB I | caro3 





are identical to the diagrams associated with SORT7. 

It is also possible to create a subroutine procedure 
from the common portions of SORT8 and SORT7. Such oe 
a procedure, SORT9, appears in Figure 3G1-5. This rou- 
tine uses a pointer array P as a parameter to sort structures 
that are not necessarily members of an array. 

Parameter P is a one-dimensional array of pointers that 
can be associated with argument arrays of arbitrary size 
(as indicated by the asterisk in the dimension attribute of Figure 3G1-3. Array of pointers and individual structures after sort 
P). The actual size of the array passed to P during an in- 
vocation of SORTS is ascertained by the built-in function 
DIM. The contents of the argument array are the absolute 
addresses of the structures to be sorted. Each structure 
must have the same attributes as the based variable IMAGE. 

Upon completion of SORTS, successive addresses in the 
argument array specify the order (from low to high) of the * 
sorted structures. 


| ADDRICARD4) -_ 






iwi? | FOURTH | 






P(5) | ADDRICARD?) | 


| DATA 
| THIRO | 


LOW 





S=P(1}; S—~>IMAGE , CARD? 


KEY | DATA | 


\ | [wey | pata 
S=P(2); $—>IMAGE ——\—fgeoo—b CAR 
KEY | DATA | \/ SECOND | 


= CARD?2 | 
~ | AMIE | SECOND \ 
: 7 S=P(3); S->IMAGE , . 7 Bae or CARDS 
| KEY DATA | . |A | | 


p.¢ P(3) | ADDR(CARD3) pot | éanbs 
S=P(4); S$ —>IMAGE Ae ma osomeS TREES CARDS 


| | aia | FIRST | 
~twi7 | FOURTH | 


CARD1 
4 271 


FIFTH | 


P(1) ADOR(CARD1) 





P(2) ADDR(CARD2) 






P(4) ADOR(CARD4) 


KEY | DATA 






i 4+ CARD4 
P(5) ADDR(CARDS) ow : DATA” a ) 
| KEY | DATA | THIRD 
CARD5 nee 


THIRD HIGH 


Figure 3G1-4. Sequential references to the sorted individual 
Figure 3G1-2. Array of pointers and individual structures structures 
before sort 
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SORTY: 
PROCEDURE (P)5 
DECLARE 
P(*) POINTER, 
T PUINTER, 
1 IMAGF BASED (S)- 
2 KEY CHARACTER(3), 
2 DATA CHARACTER(TT7T)3 
SORT: 
TEST = O03 
LOOP: 
DU 
I = 1 TO (DIM(P,1)—-1)5 
5S = P (1)3 T = PIT + 1Ld5 
If 
(S->IMAGEeKEY) > (T->IMAGF.KEY) 
THEN 
DO$ 
TEST = 13 PUT) = Ts PCT + 1) = S5 
END; 
FND 
LOOP; 
IF 
TEST = 1 
THEN 
GO TO 
SORT; 
RETURN; 
END 
SORTS; 


Figure 3G1-5. A subroutine procedure that sorts structures not 
in an array 


3G2. Linking Data Items through Pointer Variables 


An alternative method for organizing scattered data 
items into a collective unit appears in procedure SORT10 
of Figure 3G2-1, which links the scattered items through 
a pointer variable attached to each item. This technique 
is a generalization of the method employed earlier by 
SORTS, in which subscript values were used to link the 
members of an array. Procedure SORT 10, however, uses 
pointer values to link scattered items, which may or may 
not be members of an array. 

SORT 10 uses five individual but identical structures: 
CARD1, CARD2, CARD3, CARD4, and CARDS. Each 
structure contains a three-character element, KEY; a 77- 
character element, DATA; and a pointer element, L. 

The program begins by assigning input data to each 
structure. It then assigns the absolute address of each 
structure to pointer L in the previous structure. The ad- 
dress of CARD 1 is assigned to a pointer called HEAD, and 
pointer L in CARDS receives a null address value (see 
Figure 3G2-2). 

At this point in the program, the structures form a 
chain. Pointer HEAD specifies the location of the first 
structure in the chain, and pointer L of each structure con- 
tains the location of the next structure. A null address © 
for a pointer L indicates the end of the chain. 

As SORT 10 compares the KEY fields of successive 
pairs of structures, required interchanges are performed on 
the address values of the HEAD and L pointers, rather 


than on the data values of the structures themselves; as a 
result, less data is moved during the sort. 

References to the chained structures use the based vari- 
able IMAGE qualified by an appropriate pointer. Since 
several structures in the chain may be referred to at the 
same time during an interchange, intermediate pointer 
variables, such as S, T, U, and V, are used to qualify simul- 
taneous usages of IMAGE. 

At the completion of the sort, as illustrated by Figure 
3G2-3, the structures remain in their original (physical) 
positions, but the HEAD and L pointers link the structures 
in ascending order on their KEY elements. 

The steps in Figure 3G2-4 show how SORT10 uses the 
following statements to transpose the order of the first 
two structures, CARDI and CARD?2: 


S = HEAD-->IMACE.L; 
T = S—>IMAGE.L; 

S —>IMAGE.L = HEAD; 
HEAD—>IMAGE.L = T; 
HEAD = S; 


Observe that the interchange of the two structures CARD] 
and CARD2 requires modification of three pointer vari- 
ables: HEAD, CARDI.L, and CARD2.L. 

Figure 3G2-4 (step 4) shows how the structures are 
linked after the first interchange has been completed. At 
that point in the sort the structures are linked in the fol- 
lowing order: 


CARD2, CARD1, CARD3, CARD4, CARDS 


This is the logical order in which the structures are linked; 
their original physical order remains unchanged. 


When an interchange does not involve the logically 
first structure in the chained sequence, pointer HEAD is 
not modified; and, as the steps in Figure 3G2-5 show, 
SORT 10 uses a different set of instructions for the inter- — 
change. 


U = HEAD; 

S = U—>IMAGE.L; 

T = S—>IMAGE.L; 

V = T—>IMAGE.L; 
T-->IMAGE.L = U—>IMAGE.L; 
U—>IMAGE.L = S—SIMAGE.L; 
S—>IMAGE.L = V; 


These instructions are executed under control of a DO- 
loop, each cycle of which advances the pointers 5, T, U, 
and V to successive structures. Assignment of a mull value 
to T terminates the loop. 


SORT10: 

F3G2_1: 

PROCEDURE OPTIONS (MAIN); 
DECLARE | 

(HEAD, Sy Ty Us V) POINTER, 

IMAGE BASED(S)>, 

KEY CHARACTER(3) » 
DATA CHARACTER(77), 
tL POINTER, 

CARD1» 

KEY CHARACTER(3) > 
DATA CHARACTER(77), 
L POINTER, 
CARD2, 

KEY CHARACTER(3), 
DATA CHARACTER(77), 
L POINTER, 

CARD3, 

KEY CHARACTER(3) >» 
DATA CHARACTER(TT7), 
L POINTER, 

CARD4, 

KEY CHARACTER(3), 
DATA CHARACTER(77), 
L POINTER, 

CARDS, 

KEY CHARACTER(3) » 
DATA CHARACTER(77), 
2 tL POINTERS 

: ON ENDFILE (SYSIN) 
BEGIN; 


MME RRR RRR EH RRND NRE RD 


CLOSE FILE (SYSPRINT); 
GO TO 
PROC_END3; 
END; 
INPUT: 
GET 
EDIT(CARD1L.KEY, CARDIL.DATA, 
CARD2.KEY, CARD2.DATA, CARD3.KEY, 
CARD3eDATA», CARDG.KEY, CARD4.DATA, 
CARDS.KEY, CARODS.DATA) (A(3), 
A(7TT))3$ 
HEAD = ANDR(CARDI)3$ 
CARD1.eL = ADOR(CARD2)3$ 


CARD2.L = ADDRICARD3) 3 
CARD3.L = ADDRICARDS) § 
CARD4.L = ADDRI(CARDS); 
CARDS.L = NULL; 


SORT: 
K = 03; S = HEAD->IMAGF.L; 


IF , 
(HEAD-—>IMAGE.KEY) > (S—>IMAGE.KEFY) 
THEN 
DO$ 
K = 13 T = S->IMAGE.LS 
S->IMAGE.L = HEAD?; 
HEAD->IMAGE.L = T3 HEAD = S3 
END; 
U = HEAD$ S = U=>IMAGE.L; 
T = S-—>IMAGE.L3 
DO 
WHELE (T>=NULL) 5 
IF 
(S->IMAGE.KEY) > (T->IMAGF.KEY) 
THEN 
DOs 
K = L$ V = T—=>IMAGE.LS 
T—> IMAGE.L = U-> IMAGE.L; 
U->IMAGE.L = S->IMAGF.L3$ 
S->IMAGE.L = V3 
END; 
. U = U->IMAGE.LS S = UK>IMAGE.L 
T = S=>IMAGE.L; 
END; 
IF 
K = 1 
THEN 
GO TU 
SORT; S, = HEAD; 
OUTPUT: 
DU 


WHILF (S-~=NULL)3$ 
PuT 
EDI T(S->IMAGE.KEY: S->IMAGE.DATA) 
(AC3)_5 AUT7))$ 
PUT 
SKIPS 
S = S->IMAGE.L; 
END 
OUTPUT; 
PuT 
SKIP; 
GO TO 
iNPUT; 
PROC_END: 
END 
SORT1O$ 


Figure 3G2-1. Sorting structures that are linked by pointers 


The steps in Figure 3G2-5 illustrate the effect of the 
second interchange, which involves CARD1 and CARD3. 
And Figure 3G2-5 (step 4) shows the structures are linked 
in the following order after this second interchange has 
been completed: : 


CARD2, CARD3, CARD1, CARD4, CARDS 


A complete sort of the structures produces the follow- 
ing order: 


CARD3, CARD2, CARDS, CARD4, CARD1 


Figure 3G2-6 shows how the sorted structures may be 
referred to in succession. Observe how a DO statement 
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can be used to move through the chain to a particular 


structure. Also note the similarities between qualified 


pointers in Figure 3G2-6 and subscripted subscripts in 
Figure 3C2-6 (associated with SORTS). 

Structures linked by pointer variables may also be 
sorted with a subroutine, as demonstrated by procedure 
SORT 11 in Figure 3G2-7. This routine uses element- 
pointer variable HEAD as a parameter. The associated 
element-pointer argument in an invocation of SORT 11 
specifies the first structure in the chain of structures being 
sorted. 

The structures are linked as in SORT 10, and a null link 
indicates the end of the chain. The chain must contain at 
least two structures; otherwise, the number of structures 
is arbitrary. 
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CARD3 
pata FIRST ADDR(CARD2) 


FOURTH ADDRI(CARD1) 







CARD4 





KEY DATA L 
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KEY | DATA L 
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. Figure 3G2-3. Linked structures after sort 
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Figure 3G2-2. Linked structures before sort 


40 

















q 
Step 1 S - HEAD ->IMAGE.L; T = S ->!MAGE.L; Step 2 S—>IMAGE.L = HEAD: 
HEAD HEAD 
| ADDRICARD1) } | ADDRICARD1) Lo 
CARD1 CARD1 
[key | oara | ok 
jm | FIFTH | ADDRICARD2) a p27 | FIFTH | ADDRICARD2) | 
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ADDRICARD2) | : | 96 | SECOND | ADDRIcARD3) [™ | ADDR(CARD2) | & | 496 | SECOND | 



























CARDS 










ADDRICARD2) | 


ADDRICARD3) | 


wi7 | FOURTH | ADDRICARDS) | 






Step 3 HEAD—> IMAGE.L= T; HEAD Step 4 HEAD =S; 


| ADDRICARD?) Ls 







[Key | DATA 



















ADDRICARD2) | ADDRICARD2) | ass | SECOND | ADDRICARD?) | 





detest sre ant A INNER PRR 


CARD3 





ADDRICARD3) | | | ADDRICARD3) 






FOURTH | ADDRICARDS) | 


Figure 3G2-4. Performing the first interchange, which involves CARD1 and CARD2 


Step 1 U - HEAD;S = U ->IMAGE.L; T = S ->IMAGE.L; V = T ->IMAGE.L: 


HEAD 


ADDRICARD2) 


CARD1 


DATA 


ie FIFTH ADDRICARD3) | 


eae | 


ADDRICARD2) 
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DATA L 


| SECOND | ADDRICARD1) 
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Figure 3G2-5. Performing the Second Interchange, which involves CARD 1 and CARD 3 
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ADDR(CARD3) HEAD 


LOW | 


FIFTH NULL 


S = HEAD; S —->IMAGE CARD1 


CARD2 
SECOND ADDR(CARDS5) 


DATA 


FIRST ADDRI(CARD2) 


S = HEAD; S = S —>!IMAGE.L; S —-> IMAGE 


<=] 


S = HEAD: DO! = 1 TO 2;S = S —>IMAGE.L; END; S -> IMAGE CARD3 


DATA 
CARD4 © 
FOURTH ADDRI(CARD1) 


DATA 
CARDS 
THIRD ADDR(CARD4) 


Lae 


S = HEAD: DO! = 1 TO 3;S = S ->!IMAGE.L; END; S —->IMAGE 


S = HEAD: DOI = 1 TO 4;S = S —>IMAGE.L; END; S —>IMAGE 


HIGH 


Figure 3G2-6. Sequential references to the sorted sequence of linked structures 


SORTLL: IF 
F3G2_7: (S—>IMAGE-KEY) > (T-—>IMAGE.KEY) 
PROCEDURE (HEAD); THEN 
DECLARE Aine 
9 
(HEAD, Sy Ty Us V) POINTER, K = 13 V = T->IMAGE.L3 
YE eee T->IMAGE.L = U->IMAGE.L;3 
2 (KEY CHARACTER (3), | =p 
DATA CHAR EG VERGE _ U->IMAGE.L = S->IMAGE.L3 
L POINTER); ee 
. S—>IMAGEeL = V3 
SORT? END; 
ee Ke 03 Se HERDED EMAGE sh U = U->IMAGE.L; S = U->IMAGE.L;3 
(HEAD-> IMAGE.KEY) > (S->IMAGE.KEY) te Segnoeeet 
END} 
THEN 
IF 
DO; yee 
K = 13 T = S—>IMAGE.L3 eoeN 
S->IMAGEeL = HEADS, eer 
HEAD->IMAGE.L = T3 HEAD = S3 : 
SORTS 
ENDS RETURN; 
U = HEAD: S = U->IMAGE.L; END : 


WHILE (T>=NULL) 3 


Figure 3G2-7. A subroutine procedure that sorts structures linked by pointer variables 
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3H. REVIEW OF TECHNIQUES FOR ADDRESSING 
DATA ITEMS 


This chapter has shown how the movement of data may 
be reduced by manipulating the address of a data item 
rather than the item itself. The discussion has been con- 
cerned mainly with two types of addresses: relative ad- 
dresses (subscript values) and absolute addresses (pointer 
values). Since programmers are generally more familiar 
with subscripts than with pointers, addressing techniques 
were developed first in terms of subscripts and then ex-: 
tended to include analogous usage of pointers. 

The first technique for reducing the movement of data 
used an auxiliary array of address values, which permitted 
a set of cards to be sorted without actually moving the 
cards. An illustration of the subscript version of this 
technique appears in Figure 3H-1. An array of structures 
contains the cards being sorted, and an auxiliary array of 
subscript values specifies the order of the cards. Rear- 
ranging the subscript values rather than the cards reduces 
the movement of data. An illustration of the same tech- 
nique in terms of pointer values appears in Figure 3H-2. 
Since pointer values are absolute addresses, there is no 
need for the cards being sorted to be contained in an 
array; the cards can be scattered throughout storage. Both 
versions (subscript and pointer) of this technique were 
implemented in procedures SORT4 and-SORTS8. 

Once it was seen how an auxiliary array of address 
values could be used to specify the order of a set of cards, 
a further generalization became possible. It was not nec- 
essary to store the address values in an auxiliary array; in- 
stead, they could be attached to the cards being sorted. 
These attached addresses then permitted the cards to be 
linked in a sequential manner without actually moving the 
cards. An illustration of this technique in terms of sub- 


iF KEY (2) DATA(2) 


3 SECOND 
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Figure 3H-1. Using an auxiliary array of subscript values to sort an 
array of structures 
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Figure 3H-2. Using an auxiliary array of pointer values to sort 


scattered structures 
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Figure 3H-3. Using subscript values to link an array of 


structures in sort order 
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script values appears in Figure 3H-3. Each card (along 
with an attached subscript value) is stored in an array of 
structures. The attached subscript specifies the relative 
position of the next sorted card within the array. The 
last of the sorted cards has an attached subscript value of 
zero, and the first card in the sorted sequence is specified 
by the subscript value of variable H. This linking tech- 
nique contains the essential features of a list organization, 
with one exception. The cards cannot be scattered 
throughout storage; they must be contained in an array. 
However, the use of pointer values in place of subscript 
values removes this restriction, as shown in Figure 3H-4. 
It is this type of list organization that is discussed in the 
remaining chapters of this manual. The subscript version 
and pointer version of this linking technique were imple- 
mented in procedures SORTS and SORT10. 


HEAD 


ADDR(CARD3) 
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key | cara | ot 


4 A96 SECOND ADODRI(CARDS) ; 


FIRST ADDRICARD2) | - 
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¥ w17 FOURTH ADDRICARD1) 7 


; KEY {| DATA 
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Figure 3H-4. Using pointer values to link scattered structures in 
sort order . 


3l. 
. PL/I provides three major types of data addresses: 


SUMMARY OF CHAPTER 3 


symbolic, relative, and absolute. 


. Symbolic addresses permit mnemonic names to be 
cused in place of numeric addresses. 


. Relative addresses are subscript expressions that speci- 


fy the relative locations of items within arrays. 


. Absolute addresses specify the actual locations of 


items within storage. 


. The built-in function ADDR obtains the absolute ad- 


dress of a data item. The value of the built-in function 
NULL identifies no generation of storage; it is used to 
test for unallocated storage, and to indicate the end 

of a list. 


. The attribute POINTER declares an identifier to be a 


pointer variable, which has an absolute address for its 
value. PL/I also permits arrays of pointers to be de- 
clared. 


. The attribute BASED (element-pointer-variable) de- 


clares an identifier to be a based variable, which asso- 
ciates descriptive information with a pointer variable. 
The descriptive information determines the storage 
characteristics at the location given by the pointer 
variable. A based variable may be an element, an ar- 
ray, a structure, or an array of structures. 


. The pointer qualification symbol (—>) allows different 


pointer variables to be associated with the same based 
variable. The reference on the left of a pointer qual- 
ification symbol must be an unsubscripted, nonbased 
element-pointer variable, or a usage of the built-in 
function ADDR. The reference on the right of the 
pointer qualification symbol must be a based variable. 


When a reference to a based variable is not explicitly 
qualified by a pointer variable, the reference is as- 
sumed to be qualified by the pointer variable given in 
the BASED attribute associated with the based vari- 
able. 


An identifier is contextually declared to be a pointer 

vartable by its appearance in one of the following 

contexts: 

1) ina BASED attribute 

2) in the SET option of READ, LOCATE, and ALLO- 
CATE statements 7 

3) on the left of a pointer qualification symbol (—>). 


. A pointer variable receives a value through either the 


assignment statement or the SET option of READ, 
LOCATE, and ALLOCATE statements. 


Only the comparison operators equal (=) and not 
equal (17=) may use pointer variables as operands. 


. Pointer and based variables permit reductions in data 


movement and allow associations to be formed among 
scattered data items. 


Chapter 4. Lists and the Dynamic Allocation 
of Storage 


The preceding chapter showed how pointer variables and 
based variables may be used to reduce data duplication 
and data movement when scattered data items are organ- 
ized into collective units within internal storage. A re- 
striction underlying the addressing techniques of the 
preceding chapter, however, is that all storage locations 
‘associated with based variables must be declared and allo- 
cated independently of the based variables. As a result, 
the number of different storage locations that are to be 
associated with based variables must be known at the time 
a program is written. This requirement severely limits the 
applications of based variables to problems that have well 
defined storage needs and, for all practical purposes, 
eliminates those applications that determine and allocate 
needed storage during the course of program execution. 

This chapter presents methods for eliminating these 
restrictions, so that storage may be allocated dynamically 
for based variables as the need arises during program exe- 
cution. The discussion also shows how the data-address- 
ing techniques of the previous chapter and the storage- 
allocation techniques of this chapter may be combined to 
form the basic facilities for list organization and manipu- 
lation. | 


4A. BASED STORAGE 


When storage is allocated, an association occurs between 
a variable and a specified amount of storage. This associ- 
ation can occur before program execution begins and can 
remain in effect until the program is terminated; in this 
case, the allocation is said to be static. It is also possible 
for storage to be allocated after program execution begins 
and for the storage to be released (freed for possible reuse) 
before the program has finished; this type of allocation is 
called dynamic. 

The storage-class attributes determine which type of 
allocation applies to a given variable. STATIC specifies 
static storage allocation. AUTOMATIC, CONTROLLED, 
and BASED each specify a type of dynamic storage allo- 
cation: 


A. Automatic storage allocation for a variable occurs 
automatically when program control enters the block 
in which the variable is declared. Termination of a 
block automatically frees the automatic storage inter- 
nal to the block. Freeing the automatic storage asso- 


ciated with a variable causes the value of the variable 

to be lost. 

B. Controlled storage allocation permits the programmer 
to have direct control over allocation by means of the 
ALLOCATE and FREE statements. 


C. Based storage allocation also provides direct control 
over allocation by means of the ALLOCATE and 
FREE statements but, unlike controlled allocation, 
permits concurrent references to multiple storage areas 
allocated for the same based variable. 


4A1. Allocating Based Storage 


Allocation of storage for a based variable is performed by 
the ALLOCATE statement, which has the following basic 
format: 


ALLOCATE based-variable; 


When executed, this statement allocates storage for the 
based variable and assigns the absolute address of the allo- 
cated storage to the pointer variable specified in the 
BASED attribute of the based variable. The attributes 
associated with the based variable determine the amount 
of storage that is allocated. | 


EXAMPLE: 


DECLARE TABLE(5) BASED(P) FIXED DECIMAL(3); 


ALLOCATE TABLE; 


These statements declare TABLE to be a based array and 
allocate storage for an array of five elements, each of 
which is a three-digit fixed-point decimal integer. The 
location of the allocated storage is automatically assigned 
to pointer P. 

Reallocation of storage for a based variable does not 
free previously allocated storage for the variable. Instead, 
both the old storage and the new storage are availabie, 
provided the old value of the associated pointer is saved 
before it is replaced by the location of the new storage. 
Several allocations of storage for the same based variable 
may be distinguished by appropriate pointer qualification. 


AS 


EXAMPLE: 


DECLARE T POINTER, 
SWITCH BASED (P) BIT(2); 
ALLOCATE SWITCH; 
T=P; 
ALLOCATE SWITCH; 
T—>SWITCH = ‘11’B; 
SWITCH = °10’B; 


In this example, SWITCH is a based variable that repre- 
sents a two-position bit string. T and P are pointer vari- 
ables. After each allocation of storage for SWITCH, 
pointer P contains the address of the allocated storage. 
Pointer T is used to save the address of the first allocation 
before the second allocation is executed. The statement 
T—>SWITCH = ‘11°B; assigns the bit-string constant ‘11’B 
to the first storage location allocated for SWITCH, and the 
statement SWITCH = ‘10’B; assigns the constant ‘10’B to 
the second storage location allocated for SWITCH. 

Note how reallocation of based variables differs from 
that of controlled variables. Although reallocation of a 
controlled variable does not destroy its previously allo- 
cated storage, only the most recent allocation is available 
at any given time. Effectively, successive allocations of 
storage for a controlled variable are stacked. Execution of 
the FREE statement for a controlled variable releases the 
current storage allocated for the variable and makes the 
previous allocation available. Repeated execution of the 
FREE statement for a controlled variable will eventually 
release all storage that has been stacked for the variable. 
The FREE statement has no effect on a controlled variable 
that has no storage currently allocated for it. 


4A2. The SET Option in an ALLOCATE Statement 


As illustrated in the preceeding example, each allocation 
of storage for a based variable assigns the address of the 
new allocation to the pointer variable specified in the 
BASED attribute associated with the based variable. When 
two or more allocations of storage are performed concur- 
rently for the same based variable, the addresses of previ- 
ous allocations must be saved in separate pointer variables; 
otherwise, the addresses will be lost. So-far, the address 
of a previous allocation has been saved by means of the 
assignment statement. PL/I, however, provides the SET 
option in an ALLOCATE statement as an alternative 
method for assigning the address of an allocation to a 
pointer variable. 

An ALLOCATE statement with a SET option has the 
following form: 


ALLOCATE based-variable SET (element-pointer- 
variable); 
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This statement allocates storage for the based variable’ and 
assigns the address of the allocated storage to the pointer 
variable specified in the SET option. The pointer variable 
must represent a single pointer value; it cannot be the 
name of an array of pointers or a structure of pointers. 
An ALLOCATE statement without a SET option is 
treated as having an implicit SET option that applies to 


_ the pointer variable in the BASED attribute of the allo- 


cated variable. An explicit SET option allows the pro- 
grammer to specify a pointer variable different from the 
one giver in the BASED attribute of tne alto. 2te2 variable. 
This other pointer receives the address of the allocated 
storage, and the pointer variable in the BASED attribute 
remains unchanged. 


EXAMPLE: 


_ DECLARE P POINTER, 
VALUE BASED (Q) FLOAT; 
ALLOCATE VALUE; 
ALLOCATE VALUE SET (P); 


The first ALLOCATE statement allocates storage for 
VALUE and assigns the location of the storage to pointer 
Q. The second ALLOCATE statement allocates additional 
storage for VALUE and assigns the location of this new 
storage to pointer P. The value of pointer Q and the stor- 
age allocated by the first ALLOCATE statement remain 
unchanged by the second allocation. 

A single execution of an ALLOCATE statement may ~ 
perform multiple allocations of storage. 


EXAMPLE: | 
ALLOCATE VALUE, VALUE SET(P), SWITCH; 


This statement is equivalent to the following set of state- 
ments: 


ALLOCATE VALUE; 
ALLOCATE VALUE SET(P); 
ALLOCATE SWITCH; 


_Commas separate multiple references in an ALLOCATE 
statement. References to both based and controlled vari- 
ables may appear in the same ALLOCATE statement. - 


4A3. Freeing Based Storage 


Storage allocated for a based variable is freed for possible 
reuse by the FREE statement, which has the following 
basic format: 


FREE based-variable; 


This statement frees the storage currently associated with 
the based variable. The program obtains the address of 
this storage from the current value of the pointer variable 
declared in the BASED attribute of the based variable. 
The attributes of the based variable determine the amount 
of storage that is freed. 


EXAMPLE: 


DECLARE P POINTER, 

ITEM BASED(Q) CHARACTER(10); 
ALLOCATE ITEM; 
ALLOCATE ITEM SET(P); 


FREE ITEM; 
FREE P—>ITEM; 


In these statements, P and Q are pointer variables, and 
ITEM is a character-string based variable. Two allocations 
of storage occur for ITEM. Pointer Q contains the loca- 
tion of the first allocation; pointer P, the second. The 
first FREE statement frees the storage for ITEM at the 
location specified by Q. The second FREE statement 
frees the storage for ITEM at the location specified by P. 

A based variable can be used to free storage only if that 
storage has been allocated for a based variable with the 
same attributes, including array bounds, string lengths, 
and arithmetic precisions. An attempt to free a based 
variable that has not been allocated produces unpredict- 
able results. 


4A3A. Multiple References in a Free Statement 


A single FREE statement may free storage for two or 
more based variables in one execution of the statement. 


EXAMPLE: 
FREE P—>ITEM, ITEM; 


This statement is equivalent to the following set of state- 
ments: 


FREE P—>ITEM; 
FREE ITEM; 


Commas separate multiple references in a FREE state- 
ment. References to both based and controlled variables 
may appear in the same FREE statement. 


4A3B. Implicit Freeing of Storage 


Under the following conditions, based storage is freed 
without the use of an explicit FREE statement: 


A. Based storage that has been allocated in an input/out- 
put buffer by the LOCATE statement is freed after the 
value of the associated variable is written into a file. 


B. Storage that has been effectively allocated by a READ 
statement with a SET option is freed by the next 
READ or CLOSE operation for the file. 


C. All storage is freed at the end of the task in which it 
was allocated, unless it was allocated within a storage 
area belonging to another task. 


4A4. An Example of Based Storage Used in a Sort 
Procedure 


Procedure SORT12 in Figure 4A4-1 obtains successive 
sets of input cards from the standard system input file 
(SYSIN). A control card precedes each set and contains 
a number that specifies the number of cards in the set. 
The number in the control card does not include the con- 
trol card itself. The procedure sorts the cards of each set 
into ascending order on the first three characters of each 
card. It then puts the sorted cards (still preceded by their 
control count) into the standard system output file 
(SYSPRINT). These steps are repeated until all sets of 
input cards have been processed. 

When the control card for a set of input cards is read 
and control enters the BEGIN block PROCESS, an array 
of pointers P is allocated automatically. The number of 
elements in P equals the number of cards in the set (that 
is, the number in the first column of the control card). 
SORT 12 then allocates based storage for the cards of the 
set as they are read and assigns the locations of the cards 
to the elements of pointer array P, which is used to sort 
the cards. 

Actual sorting is performed by the subroutine-proce- 
dure SORT9, which appeared in Figure 3G1-5. The in- 
voking reference to SORT9 contains pointer array P as an 
argument. When control returns from SORT9, the succes- 
sive pointer values in P specify the locations of the cards 
in sort sequence. The DO-group named OUTPUT succes- 
sively assigns the card locations in the pointer array P to 
the pointer S. The reference S—>IMAGE is used to print 
each card in sort sequence. 

Before processing continues with the next set of input 
cards, the storage allocated for the present set of cards and 
for array P is freed. The automatic storage for array P is 
freed when control leaves the BEGIN block PROCESS. 


47 


SORT1L2: 
F4A4_13 
PROCEOURE OPTIONS (MAIN); 
DECLARE 
IMAGE BASED (S), 
KEY CHARACTER (3), 
DATA CHARACTER (77), 
FIXED DECIMAL (1)3 
ON ENDFILE (SYSIN) 
BEGIN; 
CLOSE FILF (SYSPRINT); 
GO TO 
PROC_END; 


ZN KN = 


EDIT (N) (FOLD) 
GET 
SKIP; 
PROCESS: 
BEGIN; 
DECLARE 
P(N) POINTERS 
CARDS: 
DO. 
I = 1 TONS 
ALLOCATE IMAGE; 
P(I) = S3 
GET 
EDI T(S=>IMAGE)(A(3), A(77))3 
END 
CARDS$ 
CALL SORTS (P)3 
COUNT: 
PuT 
DATA (N)35 
PUT 
SKIPSs 
UUTPUT: 
DO 
1 TO Ns 
P(I); 


ome 
Tn 


PUT 
EDIT(S—>IMAGE)(A(3), AUT7))5 
PuT 
SKIP$3 FREE S~->IMAGE3 
END 
UUTPUT ; 
PUT 
SKIP S$ 
NEXT: 
GO TO 
INPUT S$ 
END 
PROCESS? 
SORT9: 


F3G1_5: 
PROCEDURE (P)3 


DECLARE 
P(*) POINTER, 
T POINTER, 
1 IMAGE BASED (S)>, 
2 KEY CHARACTER(3}), 
2 DATA CHARACTER(77)3 
SORT? 
TEST = 03 
LOOP : 
DU 
I = 1 TO (DIM(P,1I—-1)3 
S = P (1)3 T = PUT + Ide 
IF 
(S->IMAGE.KEY) > (T—->IMAGE. KEY) 
THEN 
DO; 
TEST = 13 PCI) = T3 PCL + 2) = $3 
ENDS . 
END 
LOOP; 
IF . 
TEST = 1 
THEN 
Oo TO 
SORT3 
RETURN; 
ENO 
SORTS$ 
PROC_END: 
END 
SORT1L23 
N= 53 
ALS_FIRST-------~------------~---------- h 
A96_SECOND----—------------------------2 
E02_THI&0-—~--—-——- -$- nn 3 
W17_FOURTH-------------------------~~-- " 
271_f If TH----~-—----—-----------~+-------+5 
N= 53 
AlL4_F IRS 1---------------~-------------- i 
A96_SECOND--~------—-------~-----------~- 2 
E02_THIRO------------—-----~~~-~---~---- 3 
WL? __FQURTH----~--~-~---~-—--~—--------— & 
271 _€ IF TH---------~~—------------------ 5 
N= 53 
A14_F IRS ¥~------------~~--~------------ i 
A96_SECOND--~--~--------------~--+--+~+--2 
E02_THIRD-----—---~-----~--~----—----~--- 3 
W17_ FOUR TH---—---——- - - - - re 4 
171_£ IF TH--------—-----~--------------- 5 


Figure 4A4-1. Allocating and freeing based storage for numbers of structures sorted with an array of pointers 


4A5. Allocating Based Storage for a Self-defining 
Structure 


Self-defining data contains descriptive information about 
itself, such as its size, which can be used by the program- 
mer for packing, unpacking, scanning, editing, and storage 
allocation purposes. A common application of self-defin- 
ing data occurs with variable-length input/output records 
that contain a specification of their own size. PL/I per- 
mits a based structure to be self-defining’by allowing it to 
contain either one adjustable string length or one adjust- 
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able array bound, the value of which is maintained by a 
variable within the structure itself. 

However, such a variable cannot posses a value until 
storage has been allocated for the self-defining based array. 


And since the amount of storage to be allocated depends 


on the value of this variable, a facility is needed for asso- 
ciating a value outside a based structure with a variable 
within the structure prior to allocation. This facility in 
PL/I is called the REFER option. 


4A5A. The REFER Option 


The declaration of a self-defining based structure contains 
a REFER option, which determines the amount of storage 
involved in an allocation of the structure. When storage is 
allocated for a self-defining based structure, the REFER 
option causes the value of a variable outside the structure 
to be assigned to a variable within the structure, and also 
causes this value to be used as the string length or array 
bound of a component involved in the same allocation of 
the structure. 

The REFER option has the following general format: 


element-variable REFER(element-variable) 


The element variables must be unsubscripted fixed-point 
binary variables of default precision. The variable to the 
left of the keyword REFER must not be a component of 
the self-defining based structure. This variable can be 
qualified by both a pointer variable and the name of a 
structure component if the variable is part of a structure. 
The variable to the right of REFER must belong to the 
structure that contains the REFER option. 

The REFER option can be used in the declaration of a 
based structure only as the length of a string, or as the 
bound of an array. 


EXAMPLE: 


DECLARE 1 STRING BASED (P), 
2 HEAD FIXED BINARY, 
2 BODY CHARACTER(SIZE REFER 
(HEAD)), 
SIZE FIXED BINARY: 


This statement declares STRING to be a self-defining 
based structure, which contains the two elements HEAD 
and BODY. When storage is allocated for STRING, the 
length of the character string BODY is automatically set 
equal to the current value of SIZE, and this value, in turn, 
is automatically assigned to HEAD by the program. Any 

_ reference to.STRING, other than a reference in an ALLO- 
CATE statement, uses the value of HEAD to determine 
the length of BODY. For example, the statement FREE 
STRING; uses the value of HEAD to determine the amount 
of storage to be freed. 

Note that the REFER option can appear only once in a 
structure declaration. When the option specifies a string 
length, the string must be an element variable and must be 
the last element variable in the structure declaration. 


If the REFER option appears as an array bound, the 
bound must be the upper bound of the leftmost dimen- 
sion of the array variable with which it ts used. The 
REFER option must also belong to the last array variable 
in the structure declaration or to a minor structure con- 
taining the last element of the structure. 


EXAMPLE: 


DECLARE | TABLE BASED(P), 
2 UPPER FIXED BINARY, 
2 CONTENTS(0:N REFER(UPPER)) 
CHARACTER(15): 


In the declaration of TABLE, the REFER option specifies 
N as an adjustable upper bound for the one-dimensional 
array CONTENTS. Each element in array CONTENTS 

is a String of 15 characters. 


EXAMPLE: 


DECLARE 
1 PRESSURE BASED(P), 
2 VOLUME, 
3 INDEX FIXED BINARY, 
3 POUNDS FLOAT, 
2 TEMPERATURE, 
3 FLASH FIXED BINARY, 
3 RANGE FIXED BINARY, 
3 DEGREES(T REFER(RANGE),—32:0) 
FLOAT, 
T FIXED BINARY; 


The declaration of PRESSURE uses the REFER option to 
specify T as the adjustable upper bound of the leading 
dimension of the two-dimensional array named DEGREES. 
As in the preceding example, the REFER option belongs 
to the last array in the structure. 

It should be noted that since the adjustable bound ina 
self-defining based structure must appear as the leading 
dimension of the component with which it is declared, it 
is not possible for that component to inherit a dimension 
from a higher level component. Inherited dimensions 
automatically become the leading dirnensions of the lower- 
ievel component. 


EXAMPLE: 


DECLARE 
1 SCHEDULE BASED (P), 
2 LIMIT FIXED BINARY, 
2 DISTANCE (10), 
3 RATE (25), 
3 TIME (25) FLOAT; 


In this declaration, RATE and TIME inherit the bounds 
1:10 of the leading dimension of DISTANCE. RATE and 
TIME both receive the bounds 1:10 and 1:25. Any at- 
tempt, therefore, to use the REFER option in the dimen- 
sion attribute of TIME would be incorrect. However, the 
option could appear with DISTANCE, in place of 10. 
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EXAMPLE: 


DECLARE 
1 STEAM BASED (2), 
2 VOLUME, 
3 INDEX FIXED BINARY, 
3 POUNDS FLOAT, 
2 TEMPERATURE FLOAT, 
2 LEADING FIXED BINARY, 
2 POOL (VECTOR REFER(LEADING)), 
3 GALLONS (5) FLOAT, 
3 DEGREES (5) FIXED DECIMAL, 
3 AREA (5) FLOAT, 
VECTOR FIXED BINARY; 


The REFER option is used correctly in this example, 
because it appears with the minor array of structures 
named POOL, which contains the last component in the 
based structure STEAM. When storage is allocated for 
STEAM, the lower-level components of POOL, which are 
the arrays GALLONS, DEGREES, and AREA, inherit the 
value of VECTOR as their leading upper bound. The 
value of VECTOR is also assigned automatically to the 
element variable LEADING. 

After storage has been allocated for a self-defining 
_ structure, an assignment statement can be used to change 
the value of the element variable on the right of the 
REFER option. When this change occurs, the following 
rules apply to the self-defining structure: 


A. The self-defining structure must not be freed until the 
element variable is restored to the value it had when 
allocated. 


B. The self-defining structure must not be written out 
while the element variable has a value greater than the 
value it received when allocated. 


C. The self-defining structure may be written out when 
the element variable has a value equal to or less than 
the value it received when allocated. The number of 
elements or the length of the string actually written is 


that specified by the current value of the element var- 


iable. 
EXAMPLE: 
DECLARE 


1 RECORD BASED(P), 
2 SIZE FIXED BINARY, 


2 ELEMENTS (COUNT REFER(SIZE)), 
COUNT FIXED BINARY INITIAL(100); 


ALLOCATE RECORD; 
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SIZE=90 SIZE = 90; 
WRITE FILE(OUT) FROM(RECORD); 


In this example, the first 90 values of array ELEMENTS 
are written along with the value of SIZE. An attempt to 
free RECORD at this point will create an error because 
SIZE must be restored to the value it had when allocated, 
namely, 100. Had SIZE been assigned a value greater than 
100, the WRITE statement would produce an error. 


4A5B. An Example of the REFER Option ina Sort 
Procedure 


Procedure SORT13 in Figure 4A5B-1 contains an example 
of the REFER option. This procedure processes the same 
input and produces the same results as procedure SORT12 
in Figure 4A4-1. The major difference between the two 
procedures occurs in the way based storage is allocated for 
each set of cards being sorted. SORT12 allocates storage 
individually for each card in a set and controls the alloca- 
tions by means of.a DO statement. SORT13, however, 
allocates storage collectively for all cards in a set by means 
of a self-defining array of structures called ARRAY, which 
contains the single element SIZE and a variable number of 
occurrences of the structure IMAGE. 

The number in the first column of the control card be- 
fore each set of cards specifies the number of cards in the’ 
set (excluding the control card itself). This number is 
assigned to variable N, which appears in the following ex- 
pression associated with the declaration of IMAGE: 


N REFER(SIZE) 


The expression states that the number of occurrences of 
IMAGE within ARRAY is given by N and that after stor- 
age is allocated for ARRAY, the value of N is to be as- 
signed to element SIZE within ARRAY. 

This use of the REFER option permits a single execu- 
tion of the ALLOCATE statement to allocate storage for 
all cards in a set and removes the need for individual allo- 
cations under control of a DO statement. 

As in SORT12, actual sorting is performed by subrou- 
tine procedure SORT9Y, which appeared in Figure 3G1-5 
of Chapter 3. The invoking reference to SORT9 contains 
pointer array P as an argument. When control returns 
from SORTS, the successive pointer values in P specify the 
locations of the cards in sort sequence. 

Note that the card addresses in array P cannot be used 
to qualify the based structures in IMAGE when the cards 
are printed in sort sequence. Any pointer value that qual- 
ifies a based structure within IMAGE is assumed to qualify 


SORT133 
F4A5B_1: 
PROCEDURE OPTIONS (MAIN); 
DECLARE 
ARRAY BASED(R), 
SIZE FIXED BINARY,. 
IMAGE (N REFERISIZE)) >» 
KEY CHARACTER(3), 
DATA CHARACTER(77), 
MAP BASED (T), 
KEY CHARACTER (3), 
DATA CHARACTER (77), 
FIXED BINARY, 
COUNT FIXED DECIMAL (1); 
ON ENDFILE (SYSIN) 


ZNN FM WWNDNDN FE 


BEGINS 
CLOSE FILE (SYSPRINT); 
GO TO 
PROC_FENO; 
END; 
INPUT: 
GET 
EDIT (COUNT) (CFCL))S 
GET 
SKIP S$ 
N = COUNT; 
ALLUCATE ARRAY; 
PROCESS: 
BEGIN; 
DECLARE 
P(COUNT) PUINTERS; 
CARDS: 
DO I = 1 TON; 
P(I) = AODR(IMAGE(1));$ 
GET 
EDIT (IMAGE (1)) CAB)» ACTTI)DS 
END 
CARDS$ 
CALL SORT9(P)§ 
OUTPUT: 
PUT 
DATA (COUNT); 
PUT 
SKIP; 
DO 
I = 1 TO Ns T = P(T)S 
PUT 
EDIT (T—->MAP) (AUB), AVTT))S 
PUT 
SKIPS 
END; 
PUT 
SKIP; 
FREE ARRAY; 
NEXT: 
GO TO 
INPUTS 
END 
PROCESSs 
PROC_FND: 
ENO 
SORT133 
COUNT= 5; 
Al6_f IRST——= $= 5-—— el 
A96_SECOND——~ nn nnn 2 
E02_THIRD—— <a nnn 3 
Wi 7_FOURTH-—----——----—-- = - -$- 4 
171_F 1 WH---------—--- ——- ——- - 5 


Figure 4A5B-1. Allocating and freeing based storage for a self- 
defining array of structures which is sorted with 
an array of pointers : 


the entire containing structure ARRAY and will be auto- 
matically adjusted (offset) by the number of storage bytes 
separating the specified structure within IMAGE from the 
beginning of ARRAY. To avoid this erroneous address 
adjustment, an independent based structure named MAP 
is used to refer to the cards when they are printed in sort 
sequence. 

Later examples in Chapter 5 show how the REFER 
option is used to create self-defining records in output 


files. 


4A6. Allocating and Freeing Based Storage within an Area 


PL/I provides a type of variable called the area variable, 
which reserves storage for allocations of based variables. 
The area variable permits based allocations to be grouped 
as a unit for convenient input/output transmission or as- 
signment to another area variable while maintaining the 
separate identity of each allocation. The following discus- 
sion describes how area variables are used to group based 
allocations. Later discussions in Chapter 5 present the use 
of area variables for relocating based allocations without 
invalidating the address values of associated pointer varia- 
bles. 


4A6A. The AREA Attribute 


An identifier becomes an area variable when it is declared 
with the AREA attribute, which has the following general 
format: 


AREA(expression) 


The integral portion of the value obtained from the ex- 
pression represents the size of the area in bytes. The ex- 
pression, however, is optional; when it is not used, an 
implementation-defined size is assumed by the PL/I com- 
piler. 

Although an area variable reserves storage for alloca- 
tions of based variables, it can have any storage class. The 
size of an area with static storage class must appear in the 
AREA attribute as an unsigned fixed-point decimal integer 
constant. The AREA attribute is not restricted to element 
identifiers; it also applies to array and structure identifiers. 
PL/I also provides for area arguments and parameters; and 
the asterisk notation can be used to denote the size of an 
area parameter. The DEFINED attribute can be used to 
define an area on another area, through overlay or corre- 
spondence defining; both areas, however, must have the 
same size. | 
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EXAMPLE: 


DECLARE A STATIC AREA(32767), 
B AREA, 
C AREA(N), 
D AREA(S) CONTROLLED, 
E AREA(10000) BASED(P), 
F(5) AREA(400), 
1G, 
2 H AREA(100), 
2 | AREA(200), 
2 J AREA(300), 
K AREA DEFINED B, 
L AREA (*); 


This statement specifies that: 


A. A isa static area variable that reserves 32767 bytes of 
storage. 


B. B is an automatic area variable that reserves an imple- 
mentation-defined amount of storage. 


C. Cis an automatic area variable whose size depends on 
the value of N current at the time the block to which 
it is internal is activated. 


DB. Dis acontrolled area variable whose size depends ei- 
ther on the value of S at the time an ALLOCATE 
statement allocates storage for D, or on a size specifica- 
tion in the ALLOCATE statement which overrides S. 


E. E isa based area variable that reserves 10000 bytes of 
storage on each allocation. 


F. F is an area that contains five areas, each of which re- 
serves 400 bytes of automatic storage. 


G. G is an area structure that contains the three areas H, 
I, and J. H reserves 100 bytes of automatic storage, I 
reserves 200 bytes, and J reserves 300 bytes. 


H. K is an area defined on area B. 


I. Lis an area parameter that assumes the same size as its 
associated area argument in a subroutine or function 
invocation. 


4A6B. The IN Option 
The ALLOCATE statement uses the IN option for based 


allocations within an area. The statement has the follow- 
ing general format: 


ALLOCATE based-variable EMeene ere 
IN(are a-variable); 


This statement allocates storage for the based variable 
within the specified area and assigns the location of the 
allocated storage to the pointer variable. The IN option is 
not required; when it is not used, the based variable is 
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allocated in a storage area provided by the operating sys- 
tem. When the SET option is used, it may appear either 
before or after the IN option. If the variable in an IN op- 
tion is not explicitly declared, it is automatically assumed 
to be an area variable. 

The FREE statement, as applied to based variables, has 
the following general format: 


FREE based-variable IN (area-variable); 


The IN option must appear in a FREE statement if the 
based allocation was made within an explicitly specified 
area; otherwise, the option is omitted. 


EXAMPLE: 


DECLARE STORE AREA(500) BASED (P), 
VALUE BASED (Q) FIXED DECIMAL (5,2), 
R POINTER; 

ALLOCATE STORE: 

/* P ADDRESSES AREA STORE. */ 


ALLOCATE VALUE IN(STORE); 
/* Q ADDRESSES ALLOCATION OF VALUE IN 
STORE. */ 


ALLOCATE VALUE IN(P—>STORE) SET (R); 
/* R ADDRESSES SECOND ALLOCATION OF VALUE 
IN STORE. */ 


FREE VALUE IN(STORE); 
/* FREES ALLOCATION OF VALUE ADDRESSED BY 


0.) 


FREE R—>VALUE IN(STORE): 
/* FREES ALLOCATION OF VALUE ADDRESSED BY 
R. */ 


The first ALLOCATE statement allocates 500 bytes of 
storage for area STORE and assigns the location of the 
allocated storage to pointer P. 

The second ALLOCATE statement causes storage for 
based variable VALUE to be allocated within area 


P—>STORE and assigns the location of the allocated stor- 
age to pointer Q. 

The third ALLOCATE statement causes another alloca- 
tion of VALUE (different from Q—>VALUE) within area 
P—>STORE and sets pointer R equal to the location of 
the allocated storage. 

The FREE statements employ the IN option because 
allocations of VALUE were explicitly made in STORE. 
Although the allocations of VALUE become free, the 
storage for area STORE remains allocated. 


4A6C. The AREA QN-Condition 

An attempt to allocate based storage within an area that 
contains insufficient freé storage for the allocation pro- 
duces an AREA ON-condition. If no ON-unit appears for 
the AREA condition in an ON statement, the operating 
system issues a comment and raises the ERROR condition. 

When an ON-unit is specified and a normal return oc- 
curs from the ON-unit, the ALLOCATE statement that 
raised the AREA condition is executed again. If the ON- 
unit has changed the value of a pointer qualifying (explic- 
itly or implicitly) the reference to the inadequate area so 
that the pointer value specifies another area, the allocation 
is reattempted within the new area. Failure of the ON-unit 
to provide a larger area may place the program in an error 
loop. 

Chapter 5 discusses other situations that may produce 
an AREA condition. The ONCODE built-in function can 
ascertain the type of situation that has raised the ON-con- 
dition. 


4A6D. An Example of an Area Variable in a Sort 
Procedure 


Procedure SORT 14 in Figure 4A6D-1 sorts successive sets 
of cards into ascending order on the first three characters 
of each card. The standard system-input file (SYSIN) con- 
tains the cards, and each set may contain a different num- 
ber of cards. A trailer card with asterisks in the first three 
positions signals the end of each set of cards. After each 
set is sorted, it is written with its trailer card into the 
standard system-output file (SYSPRINT). 

SORT 14 allocates storage for based variable IMAGE 
throughout the empty area A (see Figure 4A6D-2). Point- 
ér variable HEAD receives the address of the first alloca- 
tion for IMAGE (see Figure 4A6D-3). The location of 
each subsequent allocation for IMAGE is assigned to 
pointer L of the previous allocation. Pointer L of the last 
allocation receives a null address value. Storage is allo- 
cated for IMAGE throughout area A until the AREA ON- 
condition occurs. At that point, all allocations for IMAGE 
form a linked chain to which input is assigned (see Figure 
4A6D-3). 

Input cards are assigned to successive positions in the 
chain until a trailer card is read. The pointer L associated 


with the last card in storage then receives a null value, and . 
the location of the first unused storage position in the 
chain is assigned to pointer UNUSED (see Figure 4A6D-4). 

Actual sorting of the cards in storage is performed by 
subroutine procedure SORT 11 of Figure 3G2-7, which 
was discussed in Chapter 3. Pointer HEAD serves as the 
argument in the invocation of SORT11. When control re- 
turns from SORT 11, the cards-are linked in ascending sort 
order (see Figure 4A6D-5). 

After the sorted cards are written into the output file, 
the storage positions linked to pointer UNUSED are re- 
linked to the chain formed by HEAD (see Figure 4A6D-6). 
Processing then continues with the next set of cards. 

Figure 4A6D-7 contains examples of sample input and 
output for SORT14. 


4B. ORGANIZATION OF DATA IN LIST FORM 


The storage allocation and pointer manipulation tech- 
niques used by procedure SORT 14 (paragraph 4A6D) 
demonstrate basic methods for organizing and processing 
data items in list form. These methods involve the follow- 
ing general steps: : 


A. linking successive ailocations of based storage into a 
chained list (briefly called a list), which is identified by 
a pointer variable that contains the absolute address of 
the first storage component in the list 


B. inserting successive input items into the leading storage 
components of the list to form a list of data items 


C. retaining unused storage components in a separate list 


D. processing the data items in the list (this usually pro- 
duces changes in the address values of the pointer links 
attached to the data items in the list) 


E. relinking used and unused storage components into a 
single list before processing the next set of input items. 


Although these steps are general, they cre not unique. 
Alternative methods can be developed for obtaining equiv- 
alent results. For example, based storage need not be allo- 
cated throughout an area before input items are read. 
Storage can be allocated as each item is read and freed 
when processing has been completed for a set of items. 
With this technique, no excess storage would be allocated 
for a set of input items. However, allocating and {reeing 
storage repeatedly in this manner would be inefficient, 
since it is faster to allocate all necessary storage once, and 
to separate used from unused storage by pointer manipu- 
lation. 


481. The Main Parts of a List 


The list organization shown in Figure 4B1-1, while not the 
most general type of organization, illustrates the main 
parts contained in all lists. The list in this figure consists 
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SORT14: 

F4A60_1: 
PROCEDURE UPTIONS (MAIN)D$ 
DECLARE 


A AREA (1000), 

1 IMAGE BASED(S) >» 

2 (KEY CHARACTER(3), 
DATA CHARACTER(77), 

L POINTER), 

1 CARD, 

2 KEY CHARACTER(3), 

2 DATA CHARACTER(77), 

SORT11 ENTRY (POINTER); 


/* WHEN AREA CONDITION OCCURS» SET 
LAST ALLOCATED LINK TO NULL */ 
ON AREA 
BEGIN; 
IF 
S = NULL 
THEN 
EXIT; 
[->L = NULL; 
GN TO 
INPUTL3 
END; 


/* WHEN END-OF-FILE CONDITION OCCURS 


FREE BASED STORAGE, CLOSE SYSPRINT 
FILE, AND END PROCEDURE */ 
ON ENDFILE (SYSIN) 
BEGINS 
| S = HEAD; 
DO 
WHILE (S~=NUEL) S$ 
T = S—->kL$ FREE S->IMAGEs S = T5 
END; 
CLOSE FILE ( 
SYSPRINT)$ 


GU TO 

UVERSs 

END$ 
/* THROUGHOUT AREA A, ALLOCATE AND 
LINK STORAGE FOR BASED VARIABLE 
IMAGE */ 
S = NULL? 
ALLOCATE IMAGE IN(A) SET (S)3 
HEAD, T = S$ 

DO. 

WHILE (1B)3 
ALLOCATE IMAGE IN (A) SET (S)35 
T—->L = S3 T = $3 

END; 
/* 

DO ; 
WHILE(18) IS TERMINATED BY AREA 
CONDITION */ 

/* ASSIGN CARDS TO BE SORTED TO 
LINKED STORAGE */ 

INPUTL >: 
S = HEAD; 

INPUT2: 

GET | 
EDIT(CARD) (A (3), ACTT))3 
IF 


CARD.sKEY = ¢#ee® 


(HEAD, UNUSED, S» Te, Us, VI POINTER, 


THEN 


/* SAVE LINK OF LAST CARD AND 
REPLACE IT BY NULL ¥*/ 
DO; 
UNUSED = T->Ls T->L = NULLS 
GO TO 
INPUT35 
FND; 


S-> IMAGE 

T= S83 S$ 
GO TO 

INPUT 23 


CARD, BY NAME; 
S->L$ 


INPUT3: 
/* PRINT INPUT SEQUENCE */ 
PUT so 
LIST (*SORT1& INPUT: *)3 
PUT 
SKIP $ 
S = HEAD; 
DO 
WHILE (S-=NULL) $3 
PUT 
* EDIT(S=>IMAGE.KEY, S->IMAGE.DATA) 
(A)$ 
Put 
SKIP$ 
S = S=>L3 
ENDS 
PuT 
EDIT (CARD) (A(3), AC77))3 
PUT 
SKIP(2)3 
SORTM: 
CALL 
SORTLL (HEAD); 


/* PRINT SORTED CARDS FOLLOWED BY 


TRAILER CARD */ 

PuT 
LIST (*SURT14 OUTPUT: *)3 

Put 
SKIP 3 
S = HEAD; 

DU 

WHILE (S-=NULL)3 

Put 
EDIT (S—>IMAGE.KEY, S—>IMAGE.DATA) 
(A(3)5 ACTT))S 

Put 
SKIP3 
T = S$ S = S=D>L3 


- ENDS 


PUT 

EDIT (CARD) (A(3)5 ACT7))5 
PUT 

SKIP (2)3 


/* RELINK UNUSED STORAGE AND 
CONTINUE PROCESSING INPUT */ 
T=>L = UNUSED; 

GO TO 
INPUTLS 


OVERS: 
END 
SORT14$ 


Figure 4A6D-1. Allocating and linking based storage in an area for varying numbers of structures that are to be sorted 
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SURTLS INPUT: 
AO2_St COND 2 AREA A 


nen ce ee eee ee ae ae ee a ewe we we wee ee 


F34_ThHIR()------------------------------ 3 


A23_t IRS1------------------------------ 1 

eee 

SORTL® OUTPLT: 

A23_# IRS1------------------------------ i 

Ao2_SFCONU-- ------ --------------------- 2 

F34_THEROD----------------~------------- 3 NULL 
eee 


SURT14S INPUT: 


TT1_F IF TH---------------—-----~-------- 5 
A96_SECUND-----------~----------------- 2 
AL4_f IRS T------------------------------ i 
W1?_FUURTH-------------~--------------- 4 
FO2_THIRN---~-------------------------- 3 
See 


SORTL4& UUTPUT: 





Al4_FIRST------------------------------ 1 

496_S€CUNU----------------------------- 2 UNUSED 
FO2_THIRO------------------------------ 3 N 
WL7_FUURTH----~-----------~------------- 4 

?T1_F IF TH---~-------------------------- 5 

eee 





SUXT14 INPUT: 


Al4_FIRS1-----------~------------------ 1 

&96_SECUND--------~--------------------- 2 

ote ie a RNG Nese et b Figure 4A6D-2. Area A before based storage is allocated and 
eo8 linked for cards 

SURT14 UUTPUFT: 

Al4_FIRSY--------------------+--------- l 

A96_SECONO—------~+-----~-----~---------- 2 

F02_THIRU-----------~----~-------------- 3 

WET UWPUUR INS <s ssa ees5s ese reese eS 4 

aes 


SORTI4S INPUT: 


W17_FUURTH-----~------------------------ 4 
1T1L_f IF TtH------------------------------ 5 
AY6_St CUND--- --~----------------------- 2 
LT1_SIXTH------------------------------ 6 
Al4_F IRS 1--~---~----------------------- 1 
FU2_THIRL----~------------------------- 3 
eee 


SORTIS GUTPUT: 


ALG_FIRST--~-~-------~------------------ i 
A36_St CONI~------------------- = - 2 -- 2 
FC2_TRI RU --- - 2 ee ne er enn nnn 3 
Wh FUURT NH --- - 2 - - ee - - 4 
TAN PALER Sos Se arose ese rr sess S=== 5 
(TL_LSIXTH-~----- ----+----- - 2 2 6 
eee 


Figure 4A6D-7. Printout of cards sorted by procedure SORT14 


AREA A. 


| i 





KEY DATA 


“UNUSED | 
NULL 


Figure 4A6D-3. Linked storage before cards are read 


|e |r i |r 
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HEAD 


_t 


UNUSED 


DATS 
SECOND 


DATA 
TH IR D 


DATA 
FIRST NULL 


_DATA 


Figure 4A6D-4. Linked storage after cards are read 


UNUSED | 


DATA 
SECOND 


DATS 
THIRD. Gos: 


DATA 
FIRST 


DATA 


Figure 4A6D-5. Linked storage after cards are sorted 
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AREA A 


AREA A 


ee DATA ee 


A 
m 
< 
O 
H 
+ 
> 
|r 


pf nue 


AREA A 





Figure 4A6D-6. Linked storage before next set of cards is read 


BODY 





















a a 
HEAD 
POINTER POINTER DATA POINTER POINTER DATA POINTER 
COMPONENT COMPONENT COMPONENT COMPONENT 


(ARROWS REPRESENT POINTER VALUES THAT SPECIFY THE LOCATION OF THE NEXT COMPONENT) 


Figure 4B1-1. A list with four components 
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of a head and a body. The head is a pointer variable that 
identifies the list and contains the address of the first com- 
ponent in the list. The body is a sequence of list compo- 
nents, each of which consists of a data item and a pointer 
variable. Except for the last pointer, which has a null ad- 
dress, the pointer in a component contains the address of 
the next component in the list. 

- This type of list organization always requires a head and 
permits the body of a list to contain an arbitrary number 
of components, limited only by available storage. It is 
even possible for the body of a list to contain no compo- 
nents; in this case, the list is said to be null (see Figure 
4B1-2). 


HEAD 


POINTER 


NULL 


Figure 4B1-2. A null list 






Figures 4B1-1 and 4B1-2 do not show the area within 
which storage has been allocated for list components. 
These illustrations emphasize the main parts of a list and 
deemphasize the environmental aspects of list organiza- 
tion. They also stress the close resemblance between a 

list and a one-dimensional array, the major difference 
being that successive components of a list need not occupy 
contiguous storage locations. 


4B2. Advantages of Lists 


Lists retain the advantages obtained from absolute address- 
ing: | 


A. reducing data movement 
B. associating data items in scattered locations. 


With these capabilities, items may be inserted into and 
deleted from lists without forcing other items in a list to 
be moved, as would be required with items in an array. 
Lists also give the programmer better control over storage 
allocation and permit the same storage to be used by sev- 
eral different variables at different times. Sharing storage 
in this manner also reduces the amount of storage that 
would ordinarily lie dormant in anticipation of maximum 
storage requirements for individual arrays and structures. 


4B3. Types of Lists 


Figure 4B1-1 illustrates one of the simplest types of list 
organization. However, other organizations are possible, 
and the pointer and based variable facilities of PL/I allow 
three major types of lists to be created: . 
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A. Data lists (i.e. lists of data items) | 
B. Pointer lists (i.e. lists of pointer values) 
C. Lists of lists 


A data list, as shown in Figure 4B1-1, consists of linked 
data items. This type of list, however, possesses two im- 
portant disadvantages: all data items in the list generally 
must have the same attributes, and the same data item 
cannot be shared by two or more lists at the same time; a 
distinct copy of the item must appear in each list, thus 
reducing conservation of storage. 

These disadvantages can be removed by replacing the 
data items in a list with pointer variables that specify the 
locations of data items outside the list. Such lists are 
called pointer lists because they consist of linked pointers. 
They retain the advantages of list organization while allow- 
ing the same data item to be shared (pointed to) by differ- 
ent lists and permitting the data items associated with a 
list to have different attributes. | 

Note that it is possible to allow a data list to contain 
data items with different attributes. However, such list 
must be processed on an individual basis. Pointer lists, on 
the other hand, permit general rather than specific process- 
ing techniques to be developed for all lists and still allow 
list items to possess a variety of attributes. 

It is also possible for the items in a list to be other 
lists. In this case, the containing list is called a list of lists. 
This type of organization permits lists to possess advan- 
tages analogous to those associated with multidimensional 
arrays. 7 
The techniques presented in SORT14 for inserting, de- 
leting, and rearranging items in a data list also apply to 
pointer lists and lists of lists. These advanced types of 
lists, however, permit far more complicated arrangements 
of list items than is possible with the simple linear organi- 
zation used in SORT 14. Since detailed discussion of the 
methods for organizing and processing advanced list organ- 
izations lies beyond the scope of this manual, the remain- 
der of the manual deals solely with data lists that possess 
the simple linear organization used in SORT 14. 


4C. REVIEW OF TECHNIQUES FOR ORGANIZING 
BASED STORAGE IN LIST FORM 


This chapter has shown how the ALLOCATE statement 


_ may be used to generate storage for a based variable as the 


need arises during program execution. Successive execu- 
tions of an ALLOCATE statement for a based variable 
permit multiple generations of storage to be associated 
simultaneously with the same based variable. Each gener- 


ation of storage is distinguished by a qualifying pointer, 
~ and should a particular generation of storage no longer be 


needed, it can be released by executing a FREE statement. 
Storage that has been freed becomes available for further 


allocation. Allocating and freeing storage during program 
execution generally improves the efficiency of computer 
applications that have highly variable storage requirements 
(see the application areas described in Chapter 1). 
Repeated allocation and release of storage, however, 
often increases the execution time of a program by a sig- 
nificant amount, particularly when the allocations are 
managed by the operating system. One way of reducing 
such inefficiency is to allocate required storage only once 
and to link the storage into a list. An illustration of such 
a list appears in Figure 4C-1 where 18 storage components 
have been allocated throughout an area and linked to form 
the list called UNUSED. As storage is required by other 


UNUSED 


DATA L 


DATA 


rT 


DATA L 


DATA 


DATA 


r 


DATA 


F 


cae [a 


lists, components can be unlinked from UNUSED and 
linked in turn to the new lists. Figure 4C-2 shows two 
lists (LIST1 and LIST2) that have obtained different 
amounts of storage from UNUSED. Similarly, when a 
storage component is no longer needed by a list, the com- 
ponent can be relinked to UNUSED where it becomes 
available for assignment to other lists as the need arises. 
These techniques for pooling storage were used in 
SORT14. They eliminate the inefficiency associated with 
repeated executions of ALLOCATE and FREE statements 
and at the same time maintain flexibility in storage assign- 
ment by means of address manipulation. 


AREA 


oe 


7 


DATA L 


DATA L 


DATA 


iy 


DATA DATA 


DATA 


a 


DALA L 


ia 


DATA Poe L 


j NULL 


rT 


Figure 4C-1. Allocating storage components throughout an area and linking them into a list 
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LIST1. | 


@ 


LIST2 


UNUSED 


| i 


DATA ;{} L 


DATA L 


rT 


DATA | 


r 


DATA 


DATA | 


DATA 


Figure 4C-2, Assigning unused storage components to other lists 


| DATA 


> 

ms) 

m 
: > 
az 


DATA | 


DATA | 


L 


DATA 


- DATA L 


DATA | 


| para | ot 


4D. SUMMARY OF CHAPTER 4 


A. 


The storage-class attribute BASED specifies a type of 
dynamic storage allocation. 


. The ALLOCATE and FREE statements provide direct 


control over based storage and have the following gen- 
eral formats: 


ALLOCATE based-variable SET(pointer-variable) 
IN(area-variable); 
FREE based-variable IN(area-variable); 


. Successive allocations of storage for a based variable 


are not stacked as they are for a controlled variable. 
Two or more allocations for the same based variable 
may be referred to at the same time. 


. The pointer variable specified in the SET option of an 


ALLOCATE statement receives the address of the 
based allocation. 


. An ALLOCATE statement without a SET option 


causes the address of a based allocation to be assigned 
to the pointer variable in the BASED attribute of the 
allocated variable. 


. The declaration of a self-defining based structure con- 
tains a REFER option, which has the following format: 


element-variable REFER(element-variable) 


This option determines the amount of storage involved 
in an allocation of the self-defining structure. 


. The REFER option may appear only once in the dec- 


laration of a self-defining structure, and must occur 
either as a string length or as an array bound in the 
component at the end of the structure. 


. When storage is allocated for a self-defining based 


structure, the REFER option causes the value of a var- 


iable outside the structure to be assigned to a variable 
within the structure. This value also replaces the 
REFER option and determines the string length or 
array bound of the final component involved in the 
same allocation of the self-defining structure. 


The AREA attribute has the following form: 
AREA (expression) 


This attribute specifies an area variable, which may 
have any storage class and which reserves storage for 
allocations of based variables. The expression in the 
attribute determines the amount of storage (in bytes) 
that is reserved. 


. The IN option of an ALLOCATE statement specifies 


the area within which storage is allocated for a based 
variable. When the IN option does not appear in an 
ALLOCATE statement, the operating system provides 
an area for the based allocation. 


. The IN option must appear in a FREE statement if the 


based allocation was made within a specified area; 
otherwise, the option is omitted. 


. An AREA ON-condition occurs when an attempt is 


made to allocate based storage in an area that does not 
contain enough free storage for the allocation. 


. When an ON-unit appears in an ON statement for the 


AREA condition and a normal return occurs from the 
ON-unit, the ALLOCATE statement that raised the 
AREA condition is executed again. Looping will occur 
if the ON-unit does not increase the amount of free 
storage in the associated area. 


. If no ON-unit appears in an ON statement for the 


AREA condition, the operating system issues a com- 
ment and raises the ERROR condition. 
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Chapter 5. Facilities for Relocating Data Lists 


The previous chapter showed how scattered data items 
may be linked with pointer variables to form list organi- 
zations that can be processed with a minimum of data 
movement. Many applications, however, require the com- 
ponents of a list to be moved collectively either between 
the internal and external storage devices of a computer, or 
solely within internal storage. But the list-processing tech- 
niques presented in the preceding chapter do not permit 
valid movement of a list as a unit, primarily because the 
values of pointer variables are absolute addresses which 
become invalid when the items they point to are moved 
to, or reallocated at, other storage locations. To overcome 
this limitation, PL/I provides special variables called offset 
variables, which allow list components to be linked by 
relative addresses that remain valid during list transmission 
and assignment. The linkage techniques developed in the 
preceding chapter still apply to relocatable lists, but offset 
variables are used in place of pointer variables. 

This chapter shows how lists may be treated as collec- 
tive units and how offset variables are used to form relo- 
catable lists. 


5A. TREATING LISTS AS UNITS WITHIN AREAS 


PL/I allows the elements of an array or structure to be 


referenced collectively through an array or structure name. 


Similar reference, though, is not possible with a list, be- 
cause a list is a data organization that is not explicitly 
known to PL/I. However, a list can be treated as a collec- 
tive unit by referring to the area in which the list compo- 
nents have been allocated. Internal and external move- 
ment of a list then becomes possible by transmitting the 
containing area. 


5B. ASSIGNING AREAS TO OTHER AREAS 


The name of an area may be treated as an area variable, 
the value of which is the storage currently allocated for 
the area name. Asa result, area variables can be used in 
assignment statements. When an area variable appears to 
the left of the equal sign in an assignment statement, the 
expression on the right must be another area variable or a 
function reference that returns an area. An area cannot 
be converted to any other type of data; therefore, an area 
can be assigned only to an area variable. 

No operators, not even comparison operators, can be 
applied to area variables, and only the INITIAL CALL 
form of the INITIAL attribute may appear in an area 
declaration. , 
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When an area is allocated, it automatically receives the 
empty state, which means that storage has not been allo- 
cated for any based variables within the area. An area that 
is not empty can be made empty by assigning it the value 
of an empty area, or the value of the built-in function 
EMPTY. The effect of such an assignment is to free all 
allocations of based variables within the receiving area. 
Note that the area itself does not become free but retains 
its storage in reserve for further allocations of based vari- 
ables. 

A reference to the built-in function EMPTY uses no 
arguments and has the following form: 


EMPTY 


An EMPTY reference cannot appear in an operational 
expression; its value is used solely to free storage allocated 
in a specified area. | 


EXAMPLE 


DECLARE 
(AREA1,AREA2) AREA(100), 
STRING BASED(P) CHARACTER(100); 


ALLOCATE STRING IN(AREA1) SET(P); 
P—>STRING = (100)*X’; 


AREA2 = AREAI; 


AREAI = EMPTY; 


In this example, both area variables AREA1 and 
AREA2 reserve 100 bytes of automatic storage. The 
based variable STRING is a 100-position character string, 
which is allocated in AREA] and to which a string of 100 
X characters is assigned. When AREA| is assigned to 
AREA2, the contents of both areas become equal. Assign- 
ment of the EMPTY function to AREA] frees the storage 
allocated for STRING in AREAI. 


Besides providing a convenient way of equating the 
contents of two or more area variables, area assignment 
also permits a list of based allocations to extend beyond 
the limits of a single area. For example, attempted alloca- 
tion of a variable in a based area that contains insufficient 
free storage raises the AREA ON-condition. An associated 
ON-unit for the condition can then be used to assign the 
contents of the area to a reserve area, and to empty the 
original area for further allocations. Upon return from the 
ON-unit, the allocation can be attempted again within the 
original area. 


EXAMPLE 


DECLARE 
(AREA1,AREA2) AREA(100), 
STRING BASED(P) CHARACTER(100); 


ON AREA 

BEGIN; 
AREA2 = AREAI; 
AREAI = EMPTY; 
GO TO A; 

END; 


A: ALLOCATE STRING IN(AREAI1) SET(P); 
P—>STRING = (100)'X’; 


GO TO A; 


EXAMPLE: 


In this example, both area variables AREA1 and 
AREA2 reserve 100 bytes of automatic storage. The 
based variable STRING is a 100-position character string, 
which is allocated in AREA1 and to which a string of 100 
X characters is assigned. When more than one allocation 
of STRING is attempted in AREA], the AREA ON-condi- 
tion occurs, and control transfers to the specified ON-unit 
in the ON statement. The ON-unit saves the contents of 
AREAI1 in AREA2, and empties AREA for further allo- 
cations. Control is then returned to the ALLOCATE 
statement, where another allocation of STRING is made 
in AREAI. 


5C. THE EXTENT OF AN AREA 


The amount of storage (in bytes) that is reserved when an 
area is allocated is called the size of the area and is speci- 
fied by the integral value of the expression in the associ- 
ated AREA attribute. The amount of storage that is cur- 
rently allocated for based variables within an area deter- 
mines the extent of the area, which is defined as the 


amount of storage between the start of the area and the 
end of the allocation most distant from the start. Asa 
result, the extent of an area never exceeds the size of the 
area and even can be zero when the size is not zero; a ref- 
erence to the built-in function EMPTY always produces an 
area of zero extent. 

The diagrams in Figure 5C-1 illustrate the relationship 
between extent and size for several area configurations. 
Shaded portions of the diagrams represent free storage 
that is available for further allocation of based variables. 
In AREAI of Figure SC-1, all storage has been ailocated; 
therefore the extent equals the size. In AREA2, the ex- 
tent also equals the size, but the area contains free storage. 
In this case, the end of the allocation most distant from 
the start coincides with the end of the area. The extent 
of AREA3 is less than the size. AREA4 has zero extent, 
because no based storage. is currently allocated within it. 


AREA 1 AREA 2 


a 
WLLL 
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Figure 5C-1. How area extent and area size are related 
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5D. THE EFFECT OF EXTENT ON AREA 
ASSIGNMENT —_ 


Assignment of an area effectively frees all allocations in 
the receiving area, and then assigns the extent of the area 
contents to the receiving area. All free-storage gaps are 
retained during area assignment, so that allocations within 
the assigned extent maintain their locations relative to 
each other. If the gaps were closed up, relative addressing 
techniques (which are discussed later) might become in- 
valid. 

Figure 5D-1 shows how area extents are assigned. The 
diagrams illustrate several area configurations both before 
and after assignment. Shaded portions of the diagrams 
again represent free storage. AREA and AREA2 have 
the same size but different extents. After assignment, 
both areas have the same size, extent, and contents. Note 
how the allocations in the assigned area retain their rela- 
tive positions in the receiving area. AREA3 has a larger 
size than AREAG, but the extent of AREA3 is less than 
the size of AREA4; therefore, AREA3 can be assigned to 
AREA4 as indicated. 


SE. THE AREA ON-CONDITION FOR AREA 
ASSIGNMENT 


When the extent of an assigned area exceeds the size of the 
receiving area, an AREA ON-condition occurs, and the 
content of the receiving area becomes undefined. If the 
procedure does not contain an ON-unit for the AREA 
condition, the operating system issues a comment and 
raises the ERROR condition. When an ON-unit is speci- 
fied and normal return occurs from the ON-unit, program 
execution continues from the point of interrupt. The 
same activity occurs when the AREA condition is raised 
by a SIGNAL statement. However, an AREA condition 
raised by an attempted allocation of storage produces dif- 
ferent activity when a normal return occurs from the asso- 
ciated ON-unit (see paragraph 4BSD, “The AREA ON- 
Condition’). | 

The ONCODE built-in function may be used to ascer- 
tain the type of situation that has raised an AREA ON- 
condition. ¢ 





BEFORE ASSIGNMENT 


AREA 2 = AREA 1; 
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Figure 5D-1. How area extents are assigned 
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BEFORE ASSIGNMENT 


AREA 4= AREA 3; 





AFTER ASSIGNMENT — 


TUEXTENT: 
FSF_1: 
PROCEDURE OPTIONS (MAIN)? 
DECLARE 
A AREA (4B), 
B BASED (P) CHARACTER (24), 
EXTENT RETURNS (FIXED (5)), 
COUNT FIXED (5)3 
ALLOCATE B IN (A) SET (P)3 
P -> B = (24) *X*3 
COUNT = EXTENT (A)3 
PUT LIST 
("EXTENT OF A ="{{/COUNTI]|]® BYTES®*)3- 


EXTENT: 
PROCEDURE 
(AREA) FIXED DECIMAL(5); 
DECLARE 
AREA AREA (*), 
—E FIXED DECIMAL (5), 
SPACE AREA(E) CONTROLLED; 


/* WHEN THE AREA CONDITION OCCURS, 
REALLOCATE SPACE WITH INCREASED SIZE, 
AND TRY ASSIGNMENT AGAIN. ¥*/ 
ON AREA 
BEGINS 
FREE SPACE; E = E + 13 
GO TO 
ALLOCATE_SPACE ; 
END; 


/* ALLOCATE SPACE WITH INITIAL SIZE 
OF ZERO. ¥*/ 
E = 03 
ALLOCATF_SPACE: 
ALLOCATE SPACE; 


/* ASSIGN AREA TO SPACE. IF NOT 
POSSIBLE, AREA CONDITION OCCURS. */ 
SPACE = AREA; 


/* WHEN THIS POINT IS REACHED, THE 
ASSIGNMENT IS SUCCESSFUL. FREE SPACE 
BEFORE RETURNING. */ 

FREE SPACE; 


/* RETURN COMPUTED SIZE OF SPACE, 
WHICH EQUALS THE EXTENT OF AREA IN 
BYTES. */ 
RETURN(E)$ 

END 
EXTENTS 


END TLEXTENT3 


EXTENT OF A = 24 BYTES 


Figure 5F-1. A function procedure that computes the extent of 
an area. 


5F. COMPUTING THE EXTENT OF AN AREA 


Area assignment can be used to compute the extent of an 
area. The function procedure EXTENT in Figure 5F-1 
shows one way of performing such a computation and 
demonstrates how the AREA condition may be raised 
during area assignment. EXTENT contains the parameter 
AREA, which represents the area whose extent is to be 
computed. A reference to EXTENT produces a five-digit 
fixed-point decimal integer that specifies the extent in 
bytes. 

.The function uses a work area called SPACE, which 
initially has a zero size and to which AREA is assigned. 
When the size of AREA exceeds that of SPACE, the at- 
tempted assignment produces an AREA condition. The 
associated ON-unit reallocates SPACE with its size in- 
creased by one byte and reattempts the assignment. Re- 
peated failure of the assignment causes the size (E) of 


_ SPACE to be increased until it is equal to the extent of 


AREA. At that point the function returns the computed 
extent. Faster computation of the extent is possible by 
increasing E with a large number of bytes, say 100, until 
E exceeds the extent of AREA. Rapid convergence to the 
extent is then produced by repeated halving of the two 
nearest values of E that straddle the extent. 


5G. THE LENGTH OF AN AREA 


The PL/I compiler associates each area variable with a 
control region that contains such information as the size 
of the area and the locations of free-storage gaps within 
the area. This control information is attached to the asso- 
ciated area contents when record-oriented input and out- 
put statements transmit an area variable. The length of 
the resulting record always exceeds the size of the associ- 
ated area. The amount of additional storage required for 
area control information depends upon the implementa- 
tion characteristics of the PL/I compiler and is obtained 
from the Programmer’s Guide for the compiler. 

To distinguish between area size and record length, 
PL/I uses the Jength of an area, which is the sum of the 
area size (specified in the AREA attribute) and the num- 
ber of storage bytes required by the area control informa- 
tion. During record-oriented transmission of an area var- 
iable, it is the area length and not the area size that deter- 
mines the record length. The programmer uses the record 
length in an ENVIRONMENT attribute for the associated 
file, or in a Data Definition statement under the Job 
Control Language for the Operating System. 
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5H. THE EFFECT OF AREA ASSIGNMENT ON 
POINTER VALUES 


Pointer values contained in an area that is assigned to an- 
other area become invalid in the receiving area. This re- 
striction also applies to null pointer values. 

Correct transmission of a pointer value requires explicit 
assignment of the value to a receiving pointer variable. 
Later discussions present another method, which uses 
relocatable pointers called offsets to maintain the validity 
of pointers transmitted by area assignment. 


51. ADDRESSING THE CONTENTS OF AN ASSIGNED 
AREA 


When a based variable is allocated in an area, the SET 
option in the ALLOCATE statement provides the address 
of the based allocation. Subsequent assignment of the 
area, however, does not provide a way of locating the 
based item in the new area. As an example, consider the 
following statements: 


DECLARE 
ITEM BASED(P) CHARACTER(10), 
(AREA1,AREA2) AREA(100); 


ALLOCATE ITEM IN(AREA1) SET(P); 
AREA2 = AREAI; 


Reference to ITEM in AREAI may be made through 
the expression P—>ITEM. Though AREAI has been as- 
signed to AREA2, a reference to ITEM in AREA2 is not 
possible, because the address of ITEM in AREA2 is not 
known and cannot be used to qualify ITEM. To overcome 
this difficulty, PL/I uses relative pointer variables called 
offset variables. 


5J. OFFSET VARIABLES 


Declaration of an offset variable must be explicit and is 
made with the OFFSET attribute, which has the following 
form: 


OFFSET (area-variable) 
The area variable in parentheses must be based and unsub- 


scripted, and must have an implied or explicit level number 
of one in its declaration. 
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EXAMPLES: 


DECLARE | 
AREA1 AREA BASED(P1), 
AREA2 AREA(500) BASED(P2), 
O OFFSET(AREAI), | 
(M, N) OFFSET(AREA2) EXTERNAL STATIC, 
SWITCH CONTROLLED OFFSET(AREAI), 
T(5) OFFSET(AREA2) INTERNAL, 
V(—2:2, —3:3) OFFSET(AREA2), 
1 A, 2 X CHARACTER(15), 2 Y OFFSET(AREA]), 
1 TABLES, 2 1(5) OFFSET(AREA2), 2 J(0:4) 
OFFSET(AREAI); 


As shown in these examples, PL/I allows offset variables 
to be individual element variables, or elements of arrays 
and structures. An offset variable can have any storage 
class and scope, and the usual default ruies for these attri- 
bute types also hold for an offset variable. The area vari- 
able in an OFFSET attribute must be explicitly declared. 
If it is not, the variable is assumed to be an area variable 
by its appearance in the OFFSET attribute. However, an 
error will occur, because the area variable receives the 
automatic storage class by default. This type of storage 
violates the requirement that the area variable in an OFF- 
SET attribute must have the based storage class. 

It is possible, however, to associate an offset variable 
with an area that is not based. Consider the following 
statements: 


DECLARE 
AREA1 AREA(2000), 
DUMMY_AREA AREA(2000) BASED(DUMMY _ 
POINTER), 
O OFFSET(DUMMY_ AREA): 


DUMMY _ POINTER = ADDR(AREAI); 


AREAI and DUMMY_ AREA are area variables. 
AREAI reserves automatic storage, and DUMMY_AREA 
reserves based storage. The OFFSET attribute for variable 


~Ouses DUMMY_ AREA and thus satisfies the requirement 


that the area specified in an OFFSET attribute must be 
based. When the address of AREA] is assigned to DUM- 
MY POINTER, DUMMY_ AREA becomes equivalent to 
AREA1. Subsequent references to offset variable O are 
then effectively associated with AREAI. 


The size of the area declared for DUMMY_ AREA in 
the previous example does not have to be the same as the 
size of AREA], and can even be zero. The only purpose 
of DUMMY _ AREA is to provide a level-one based area 
variable for the OFFSET attribute of variable O, so that 
variable O can be made relative to the starting address of 
AREA]. The size of DUMMY _ AREA is unimportant, 
because it does not affect the starting address assigned to 
DUMMY _ AREA through DUMMY_ POINTER. 


5J1. Assigning Values to Offset Variables 


The value of an offset variable is a relative address, that is, 
an address which is relative to (or “offset” with respect 
to) the beginning of the area associated with the offset 
variable. Addresses that are relative to an area permit data 
items within the area to be linked in list form, so that the 
address linkage of the list does not become invalid when 
the content of the area is assigned to another area (this 
point is discussed in more detail in paragraph 5K). 

An assignment statement can be used to assign a value 
to an offset variable, and the offset variable can receive 
the values of pointer variables as well as the values of off- 
set variables. When the value of a pointer variable is as- 
signed to an offset variable, the assigned value is converted 
to an offset value. The conversion is performed automat- 
ically by subtracting from the value of the pointer variable 
the absolute address of the area specified in the OFFSET 
attribute for the offset variable. The address arithmetic 
performed by the program is equivalent to the following 
calculation: 


offset value = (pointer value)—(absolute address of area) 


The offset value produced by this calculation is assigned to 
the offset variable, but the pointer variable retains its or- 
iginal value (which is an absolute address). 

Similarly, when an offset variable is assigned to a point- 
er variable, the offset value is converted to a pointer value. 
The offset value is effectively added to the absolute ad- 
dress of the area specified in the associated OFFSET at- 
tribute: 


‘ pointer value = (offset value)+(absolute address of area) 


The resulting pointer value is assigned to the pointer vari- 
able, but the offset variable retains its original value (which 
is a relative address). 

Note that the foregoing address computations are per- 
formed automatically by the program. PL/I does not 
allow the programmer to use arithmetic operations to 
specify address computations. 


When an offset variable is assigned to another offset 
variable, the offset value is assigned without modification. 
The offset variables involved in the assignment do not have 
to be associated with the same area. Consequently, an 
offset address can be made relative to more than one area; 
it is this facility that permits the construction of reloca- 
table data lists (discussed in paragraph 5K). 

The following example shows how address values are 
assigned to offset variables; it also shows how to obtain the 
absolute address of an item located in an assigned area: 


DECLARE 
AREA1 AREA(500), 
AREA2 BASED(A) AREA(500), 
DUMMY AREA BASED(DUMMY_ POINTER) AREA, 
(P1, P2) POINTER, 
Ol OFFSET(DUMMY_ AREA), 
O2 OFFSET(AREA2), 
STRING BASED(P1) CHARACTER(80); 


DUMMY_ POINTER = ADDR(AREAI]); 
ALLOCATE STRING IN(AREA1) SET(P1); 
ALLOCATE AREA2 SET(A); 


A—>AREA2 = AREAI; 


O1=P1; 
02=O1; 
P2 = 02; 


AREAI1 reserves 500 bytes of automatic storage, and 
AREA2 reserves 500 bytes of based storage. An imple- 
mentation-defined amount of based storage is reserved by 
DUMMY AREA. AREA2 is itself allocated in an area 
provided by the operating system; pointer A specifies the 
location of AREA2. STRING is an 80-position based 
character-string allocated in AREA1, and pointer P1 speci- 
fies the address of STRING in AREAi. When the address 
of AREA] is assigned to DUMMY POINTER, offset vari- 
able O1 becomes associated with AREA1. 

After AREAL is assigned to A~>AREA2, both areas 
contain equivalent storage configurations. Assignment of 
pointer P1 to offset O1 produces the relative address of 
STRING in AREA1. This relative address remains un- 
changed when assigned to offset O2. Assignment of O02, in 
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STRING 


ALLOCATE STRING IN(AREA1) SET(P1); 
ALLOCATE AREA2 SET(A); 


A —>AREA2 = AREA1; 
O1=P1; 3 7 
02=01; _ 

P2 = 02; 


Figure 5J1-1. Obtaining the address of a data item in an assigned area 


turn, to P2 produces the absolute address of STRING in 
A—>AREA2. Reference to STRING in A—>AREA2 then 
becomes possible with the expression P2—>STRING. 

Figure 5J1-1 uses assumed addresses to illustrate the 
relationship between AREA1 and A~>AREA2. The 
figure assumes AREA is located at address 1000, and 
A-—>AREAZ2 at address 2000. STRING is further assumed 
tobe located in AREA at address 1050, which becomes 
the value of P1. Assignment of AREA] to A~>AREA2 
places STRING in A—>AREA2 at location 2050. Each 
occurrence of STRING occupies the same relative position 
(50th location) in both AREA1 and A—>AREA2. 

When P1 is assigned to O1, O1 receives the relative ad- 
dress value (50 = 1050 — 1000) of P1 with respect to 
AREA|1 rather than the absolute value (1050) of P1. O2 
receives the relative address 50 through assignment of O1 
toO2. P2 then receives the absolute address value (2050 = 
50 + 2000) of O02 when O2 is assigned to P2. Note that 
direct assignment of O1 to P2 would not be correct, be- 
cause O1 is relative to AREAI and not to A~>AREA2; 
assignment of O1 to P2 produces an absolute address of 
1050 rather than the desired 2050. 

The broken lines in Figure 5J1-1 indicate offset varia- 
bles to help distinguish them from pointer variables. 
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STRING 


LE: 


/*ALLOCATE STRING IN AREA1, and SET P1.*/ 
/*ALLOCATE AREA2, AND SET A.*/ 


/*ASSIGN AREA1 TO A —>AREA2.*/ 

/*SET 01 TO RELATIVE ADDRESS OF STRING IN AREA1.*/ 
/*SET 02 EQUAL TO 01.*/ 

/*SET P2 TO ABSOLUTE ADDRESS OF STRING IN A —> AREA2.*/ 


5J2. The NULLO Built-In Function 


A null offset value can be assigned to an offset variable 
through the built-in function NULLO, which requires no 
arguments and has the following form: 


NULLO 


A reference to this function produces a null offset address, 
which specifies no relative storage location. A null offset 
address can be used to indicate the end of a list of compo- 
nents linked by offset addresses. 

. Although pointer values may be assigned to offset vari- 
ables, and offset values, in turn, may be assigned to pointer 
variables, a null offset value cannot be assigned to a point- 
er variable. Similarly, a null pointer value cannot be as- — 
signed to an offset variable in place of a null offset value. 
These restrictions apply not only to explicit references to 
NULLO and NULL but also to assigned variables that cur- 


rently have null offset and null pointer values. 


As an illustration, if P is a pointer variable and O is an 
offset variable, P can be assigned to O provided P does not 
have a null value. When the value of P might be null, an 
IF statement may be used to ensure proper assignment: 





IF P= NULL 
THEN O = NULLO; 
ELSE O=P,; 


A similar statement governs the correct assignment of O to 
P: 


IF O = NULLO 
THEN P = NULL; 
ELSE P=0O; 


5J3. Restrictions on Offset Variables 


The restrictions on pointer variables presented in Chapter 
3 also apply to offset variables, with the addition of the 
following points: 


A. An ofiset variable cannot qualify a based variable. The 
offset value must first be assigned to a pointer variable, 
which is then used to qualify the based variable. 


B. Offset values and pointer values form a special type of 
program control data called the locator type. Locator 
data cannot be converted to any other type, nor can 
any other type of data be converted to locator type. 
Offset variables can receive offset and pointer values 
only; the same restriction applies to pointer variables. 


C. Locator variables can appear as arguments and para- 
meters. An offset argument associated with an offset 
parameter, or a pointer argument associated with a 
pointer parameter requires no conversion and therefore 
produces no dummy argument. But an offset argument 
associated with a pointer parameter, or a pointer argu- 
ment associated with an offset parameter does require 
conversion and will produce a dummy. argument. Also, 
when an offset argument is associated with an offset 
parameter, both must be offset with respect to the 
same area for the argument-parameter association to be 
meaningful. 


D. The DEFINED attribute can be used for overlay or 
correspondence defining of an offset variable on an- 
other offset variable. The area variables named in the 
OFFSET attributes of the two offset variables need not 
be the same. The DEFINED attribute also applies to 
pointer variables. However, an offset cannot be de- 
fined on a pointer, nor can a pointer be defined on an 
offset. 


E. As with pointer variables, the comparison operators 
equal (=) and not equal (=) are the only two opera- 
tors that can use offset variables as operands. 


5K. RELOCATION OF DATA LISTS 


Once the components of a list have been allocated and 
linked within an area, references to the area name allow 
the list to be treated as a unit. The advantage of being 
able to refer to the list as a unit is that area assignment can 
be used to move the list to another area, such as a work 
area. The name of the area also permits collective trans- 
mission of the list to an external storage medium, such as 
magnetic tape or magnetic disk, from which the list can be 
retrieved for further processing. If area assignment were 
not available, the components of a list would have to be 
reallocated and linked individually within the new area. 
Moving the list in this manner would generally take more 
time than is required for direct assignment of the area. 

A list that is linked by pointer values, however, does 
not remain properly linked when it has been moved. The 
components of the assigned list have new addresses that 
are not specified in the linking pointers of the list. Ad- 
justment must be made to the values of the linking point- 
ers to maintain proper linkage of the list. The following 
discussions show how these adjustments are made for 
both internal and external relocation. 


5K1. Internal Relocation 


Chapter 4 showed how based allocations may be linked in 
an area to form a data list. Relocation of such a list within 
internal storage is performed, in part, by assigning the area 
that contains the list to a receiving area. As discussed | 
previously, however, the pointer values that link the com- 
ponents of the list become invalid in the receiving area 


‘ when transmission is performed by area assignment. 


Consider, for example, the incorrect area assignment 
illustrated in Figure SK1-1. B1—>BODY 1 is a based area 
that contains a three-component data list, which is as- 
signed to based area B2—->BODY2. For continuity with 
previous examples, the list components in this figure have 
the same structure organization used in Chapter 4. In the 
figure, pointer HEAD] specifies the location of the first 
list component in BI->BODY1. Offsets OHEAD1 and 
OHEAD?2 are relative to BODY 1 and BODY2 and are used 
to obtain the address value of pointer HEAD2, which 
specifies the location of the first list component in B2—> 
BODY2. As before, broken lines indicate offset address 
values. 

The following statements perform the assignment: 


B2—>BODY 2 = B1—>BODY 1; 
OHEAD!1 = HEAD 1; 

OHEAD2 = OHEAD 1, 

HEAD2 = OHEAD?2; 
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OHEAD1 = HEAD; 
OHEAD2 = OHEADT; 


82 —> BODY2 = Bi —-> BODY 1; 
HEAD2 = OHEAD2; 


Figure 5K1-1. Incorrect assignment of a data list 


These statements assign the data list in BI—>BODY1 to 
B2—>BODY2 and obtain the proper value for HEAD?2, 
but they do not maintain the validity of the component 
pointers in the receiving area B2->BODY2. The pointers 
in B2-->BODY2 have unknown values (indicated by the 
question marks) and, therefore, do not link the list compo- 
nents. Note further that the null pointer in the last com- 
ponent also becomes invalid in the receiving area. 

Even if the pointer values in the source area were trans- 
mitted to the receiving area without modification, the 
transmitted list would still be incorrectly linked, because 
the pointers would continue to specify the list components 
in the source area and not those in the receiving area. 


Proper assignment of the data list appears in Figure 
5K1-2, which illustrates the effect of the following state- 
ments: 
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These statements perform an incomplete 
assignment. Pointer values in 

B2 —> BODY 2 are not known. See 
Figure 5K 1-2 for complete assignment. 


B2—>BODY2 = BI—>BODY1; 

OHEAD!1 = HEAD; 

OHEAD2 = OHEAD!; 

HEAD2 = OHEAD2; 

TEMP1 = HEAD1; 

TEMP? = HEAD?2; 

DO WHILE(TEMP17] = NULL); 
OHEAD!1 = TEMPi—>L; 
OHEAD2 = OHEAD!; 
TEMP2—>L = OHEAD?2; 
TEMP1 = TEMP1—>L; 
SAVE = TEMP2; 

TEMP2 = TEMP2—>L; 

END; 

SAVE—>L = NULL; 


B1—>BODY1 


B2 -->BODY2 





82 ->BODY2 = B81 ->BODY1: 
OHEAD1 = HEADI: 

OHEAD2 = OHEAD1; 

HE AD2 = OHEAD?2: 

TEMP! = HEAD: 

TEMP2 = HEAD2. 


Figure 5K1-2. Correct assignment of a data list 


These statements not only assign the data list in BI—> 
BODY | to B2L—>BODY 2 but also adjust the values of the 
component pointers (the L’s) in the receiving area. Point- 
ers TEMP1, TEMP2, and SAVE serve as work pointers 
that specify the addresses of successive list components 
in B!1—>BODY 1 and B2—>BODY?2. 

The statements illustrated in Figure 5K 1-2 can be in- 
corporated into a subroutine, as shown by procedure 
MOVE _L in Figure 5K1-3. MOVE _L assigns the data list 
in one area to another area. The routine uses four para- 
meters: BODY1, HEAD1, BODY2, and HEAD2. BODY 1 
represents the area that contains the data list to be assigned 
to BODY2. Pointer HEAD! specifies the location of the 
first list component in BODY1. Similarly, pointer HEAD2 
specifies the location of the first list component in 
BODY 2 after the list has been assigned. 

The area arguments associated with parameters BODY 1 
and BODY? can be of any storage class, but MOVE. _L 
assumes that storage has been allocated for the arguments 
before invocation. If BODY2 is not large enough to re- 
ceive the contents of BODY 1, pointer HEAD? receives a 
null value. The subroutine uses based areas DUMMY _ 
BODY 1 and DUMMY _ BODY? in the declarations of off- 
sets OHEAD1 and OHEAD2 and overlays these areas on 
BODY 1 and BODY?. .As a result, BODY1 and BODY2 


DO WHILE (TEMP17~7= NULL): 


OHEAD1 = TEMP1 —>L: 
OHEAD2 = CHEADI; 
TEMP2 —>L = OHEAD?; 
TEMP1 = TEMP? —->L; 
SAVE = TEMP2; 

TEMP2 = TEMP2 —->-L: 


END: 
SAVE ->L = NULL; 


need not be of the based storage class, as would be re- 
quired if they appeared in the OFFSET attributes of 
OHEAD!I and OHEAD?2. 


SK2. Relocatable Data Lists 


The techniques used so far for assigning a data list from 
one area to another prevent the assignment from being 
direct. Not only must an area assignment be performed, 
but the pointer links of the assigned list must also be 
modified. A way of avoiding the additional programming 
needed for this pointer modification is to use offset vari- 
ables, rather than pointer variables, as component links in 
the data list. Assignment of the list, then, requires no 
change in the values of the offset links, because the list 
components maintain their relative positions in the receiv- 
ing area. Even the head of the list can be an offset varia- 
ble, in which case the relative address of the first list com- 
ponents can also be assigned directly to the receiving head. 

To distinguish between lists that are linked by pointer 
variables and lists that are linked by offset variables, the 
term absolute list is applied to a list linked by pointers 
(because pointer addresses are absolute addresses), and the 
term relocatable list is applied to a list linked by offsets 
(because offset addresses are relative addresses and hence 
relpcatanle): 
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TUMOVE LL 


PRUCELUKE UPTIONS (RAINES 


VECL ARE 


IF 
THE AREA CONDITIGN OCCURS, BO00Y2 IS 
TOO SMALL TO RECEIVE THE CONTENTS OF 


AR germ aa BODYL. SET HEAD2 TO NULL, AND 
i siwace BASEG US)y RETURN. */ 
2 KEY CHARACTER (3)¢ ON AREA 
: eae (7)> BEGINS 
1 CARL, eer HEAD2 = NULL; 
CHARA r) 
; ae CHARACTER (7) GO TO 
MOVE_L ENTRY (AREA (500)9 PTR, END _MOVE_1L 3 
AREA (500), PTR)» END: 
(HEAD Lb» HEAD_25 DyPeQe8eT) POINTERS ¢ | 
if » f*® ASSIGN BODY] YO BO0DY2. IF HEADL 
S = NULLE ; IS NULL, SET HEAD2 TO NULL, AND 
IN (BCDY_1) SET (S)3 
ere RETURN. */ 
bu BODY2 = BODYL: 
l= 1 10 43 
PE D) tA (100) = 
AR 3 ; = 
RLLDeATE IMAGE IN {BUDY_1) SET (S)3 HE ADL NULL 
T -> IMAGE.L = S3 THEN 
T= S3 DOs 
Eee yg => IMAGESL = NULL: HEAD2 = NULL 3 RETURNS 
ASSIGNS ENDS; 
bu ee a ere eee /* OVERLAY DUMMY_BODY1] ON BODY1 AND 
R -> IMAGE = CARD, BY NAME; DUMMY_BODY2 ON BODY2 SO THAT THE 
: Roe Ree AR ASE SE OFFSETS OHEADL AND QHEAD2 ARE 
o aeeiens ‘RELATIVE TO BASED AREAS. */ 
pul Dl = ADDRIBODY1) S$ 
¢ ; DY_}2°)5 
a SKIP (2) LIST CPCONTENT OF BODY D2 ss ADDR{ BODY?) 3 
WHILE (0 —= NULL}S 
Put Ss eee eed 4%® ASSIGN ADDRESS OF FIRST tistT 
Be iaee DATAY Cai Rie YG COMPONENT IN BODY2 TU HEAD2. */ 
D = D -> EMAGE.L: UHEALDL = HEADIL; 
€ : me 
ENDS HEAD_1 = P3 UHEAD2 = ONEADL3 
BOOY_2 = EMPTY; HEAD? = QHEAD23 | 
HEAD_2 = NULL: /*® ADJUST LINK POINTERS GF LIST IN 
CALL MOVE_L (RODY_1l> HFAU_1» BODY2. */ 
BODY_2¢ HEAD_2)3 TEMP] = HEADI1; 
CUTPUTs: TEMP? = HEAD2 3 
Pul : DU 
eer UATE ITEMS IN BODY_22 93 WHILE (TEMPI1-~=NULL )3 
OHEADL = TEMPL=—>L3 
- Q = HEAD_2; QOHEAD2 = OHEADIL: 
WHILE ( Q@ -= NULLS: FEMP2—>L = OHEAD2; 
earere EDIT (Q -> IMAGE.KEY TEMPL = TEMP1~>L3 
G -> IMAGE.OATAD (As 2), AD: SAVE = TEMP2; 
; Q = Q -> IMAGE.L; TEMP2 = TEMP2->L; 
oe END$ 
MOVE_L: SAVE->L = NULL? 
PROCEOURE END_MOVE_L? 
(BODY1, HEADL, BODY2, HEAD2); END 
DECLARE MOVE_L3 
. BODY] AREA(*), END 
BODY2 AREA(*), T_MOVE_L3 
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DUMMY_BODY1 AREA BASED (D1), 
DUMMY_BODY2 AREA BASED (D2). 


569 
OHEAD] OFFSET(DUMMY_BODY1) >» ace 
OHEAD2 OFFSET (DUMMY_BODY2) > $69 
1 IMAGE BASED (S)> 569 
2 KEY CHARACTER (3), KEY 
2 DATA CHARACTER (7)¢ 569 
2 L POINTER, sats 
(HEADL, HEAD2, TEMPl, TEMP2, SAVE) 569 
POINTER; nee 

ft 


CONTENT OF BUDY_1: 


$6901 2uy 
5690120 
569012Q 
5690120 
5690120 


AND DATA ITEMS IN BMDY_2: 
5690120 
5690120 
56901 2u 
5690120 
5690120 


Figure 5K1-3. A subroutine procedure that assigns a data list to another list area 


Figure 5K2-1 illustrates the organization of a reloca- 
table data list; as usual, broken lines indicate offset vari- 
ables. The figure also shows how list assignment may be 
performed with the following statements: 


B2—>BODY2 = B1—>BODY 1; 
OHEAD2 = OHEAD1; 


These statements assume that the offset links (the OL’s) in 
based area B1—>BODY 1 and the offset head OHEAD 1 are 
relative to BI1—>BODY1. Similarly, the offset links in 
B2—>BODY?2 and the offset head OHEAD2 are assumed 
to be relative to based area B2—>BODY2. The following 
statement establishes the proper declaration for the vari- 
ables used in the figure: 


DECLARE 
BODY 1 BASED(B1) AREA, 
BODY2 BASED(B2) AREA, 
DUMMY BODY BASED(DUMMY_ POINTER) AREA, 
OHEAD1 OFFSET(BODY 1), 
OHEAD2 OFFSET(BODY?2), 
1 COMPONENT BASED(COMPONENT_POINTER), 
2 KEY CHARACTER(3), 
2 DATA CHARACTER(77), 
2 OL OFFSET(DUMMY_ BODY); 


Declaration of offset variable OL with respect to DUM- 


MY_ BODY permits OL to be made relative to any area by 
assigning the address of the desired area to DUMMY _ 


81 —>B0DY!1 






82 ->BODY2 


i 


POINTER. Arbitrarily, a default area size has been as- 
sumed for BODY1 and BODY?2. If desired, a specific area 
size can be specified for each area. 

By printing the KEY and DATA values of each list com- 
ponent in B1—>BODY 1 the following statements show 
how references are made to the elements of a relocatable 
list: 

DUMMY POINTER = ADDR(B1I—>BODY 1); 

COMPONENT POINTER = OHEAD 1; 

DO WHILE(COMPONENT_POINTER™= NULL); 

PUT LIST(COMPONENT_POINTER—>KEY, 
COMPONENT POINTER—>DATA); 

PUT SKIP; | 

IF COMPONENT _POINTER—>OL = NULLO 

THEN COMPONENT POINTER = NULL; 

ELSE COMPONENT_ POINTER = 

COMPONENT _-POINTER—>OL; 

END; 


Similar statements allow printing of the KEY and 
DATA values of each list component in B2—>BODY?2: 


DUMMY_ POINTER = ADDR(B2—>BODY?); 

COMPONENT POINTER = OHEAD?; 

DO WHILE(COMPONENT_POINTER“= NULL); 

PUT LIST(COMPONENT_POINTER—>KEY, 

COMPONENT POINTER—>DATA); 

PUT SKIP; 

IF COMPONENT _POINTER—>OL = NULLO 
THEN COMPONENT POINTER = NULL; 
ELSE COMPONENT _POINTER = 
COMPONENT _ POINTER—>OL; 

END; 






B2 -> BODY 2 = B1 —->BODY!1; 
OHEAD2 = OHEAD!I; 


Figure 5K2-1. Assigning a relocatable data list 
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In each of the previous sets of statements, the address 
assigned to DUMMY _ POINTER determines the area to 
which the offset link OL becomes relative: area B1—> 
BODY 1 in the first set of statements, area B2—>BODY2 
in the second set. Conversion of offset addresses to abso- 
lute addresses is performed by assigning the offsets to the 
pointer variable COMPONENT_ POINTER. 


5K3. A Subroutine that Assigns a Relocatable Data List 
to Another Area 


The techniques developed in the previous discussion for 
assigning a relocatable data list to another area may be 
summarized in subroutine form, as shown by subroutine 
procedure MOVE_RL in Figure 5K3-1. MOVE_RL uses 
four parameters: BODY1, OHEAD1, BODY2, and 
OHEAD2. BODY 1 represents the area that contains the 
data list to be assigned to area BODY2. The relative loca- 
tion of the first list component in BODY1 is given by off- 
set variable OHEAD1. Similarly, OHEAD2 specifies the 
relative location of the first list component in BODY 2 
after the assignment has been made. If BODY2 is not 
large enough to accept the contents of BODY1, OHEAD2 
receives a null offset value. Under no circumstance does 
MOVE_RL change the contents of BODY1. 

BODY 1 and BODY?2 can be of any storage class, but 
storage is assumed to have been allocated for the corre- 
sponding area arguments upon entry to the subroutine. 


DUMMY_ BODY1 and DUMMY _BODY2 are used to 
supply based areas for the OFFSET attributes of OHEAD1 
and OHEAD2. | 

The following statements show how MOVE_RL may 
be invoked: 


DECLARE 

LIST_BODY1 AREA(S500), 
LIST_BODY2 AREA(500), 
DUMMY 1 BASED(DUM1) AREA, 
DUMMY?2 BASED(DUM2) AREA, 
LIST_OHEAD1 OFFSET(DUMMY1), 
LIST_OHEAD2 OFFSET(DUMMY2); 


DUM1 = ADDR(LIST_ BODY 1); 
DUM2 = ADDR(LIST_ BODY 2); 


CALL MOVE_RL(LIST_BODY1, LIST_OHEAD1, 
LIST_BODY2, LIST_OHEAD2); 
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TLUMUVE RL: 


PROCEDURE OPTIONS (MAINDS 
DECLARE 


00 


END 


L_BODY1] AREA (500), 

L_RBODY2 AREA (500), 
LUM_BODY1 BASED (DUM1) AREA, 
DUM_BODY2 BASED (DUM2) AREA, 
L_OHEADL OFFSET (0UM_800V1), 
L_OHEAD2 OFFSET (0UM_BODY2), 
1 ITEM BASED (P), 

2 CONSTANT CHARACTER (7), 

2 OL OFFSET (OUM_BODVL), 

Q POINTER, 

MOVE_RL ENTRY (AREA (500), 
OFFSET (OUM_BODY1L), AREA (500), 
OFFSET (0UM_BODY2))3 


DUML = ADDR (L_B0DY1); 

ALLOCATE ITEM IN (L_BODYL) SET (P)s 
L_OHEADL, Q = P3 . 

P —> CONSTANT = "NEWMOVE®; 


I= 2 70 53 

ALLOCATE ITEM EN (L_BODYL) SET (P); 
P —> CONSTANT = *MOVE_RL®; 

Q-> OL =P; Q=P; 


Q => OL = NULLO; 
DUMZ = ADDR {L_BODY2)? 
L_BODY2 = EMPTY; 
L_OHEAD2 = NULLO: 


CALL MOVE_RL (L_BODVI, L_OHEADL, 
LBODY2, L_OHEAD2); 
DURL, DUM2 = ADDR (L_BO0V2)3 


v 
SKEP LIST (*COMSTANTS IN &_8ODY2:s ° 35 


IF 


THEN 


ELSE 


ENDS 


LLOWEAD2 = NULLO 
N 


Q 2 NULLS 
€ 


Q = L_OHEAO2; 

WHELE ( Q we NULL 33 

SKIP LIST (9 -> CONSTANT); 
Q-> OL = NULLO 

Q = NULL: 


Q*= Q -> OLs 


MOVE_RL: 
PROCEDURE 


(BODY1, OHEADL, BODY2, OHEAD2); 


DECLARE 


IF 


ENDS 


BODY! AREA(*), BODY2 AREA(#), 
DUMMY_BODY1 BASED(D1L) AREA, 
DUMMY_BODY2 BASED(D2) AREA, 
OHEADL OF FSET(DUMMY_BODY1L)» 
OHEAD2 OFFSET (OUMMY_BODY2)3 
/* 7 


AREA CONDITION OCCURS, B800Y2 IS TOO 
SMALL TO RECEIVE CONTENTS OF BODYI. 
SET OHEAD2 TO NULLO, ANDO GO TO END 
OF SUBROUTINE. */ 

ON AREA 


OHEAD2 = NULLOS 
GO TO 
END_MOVE_RL$ 


/* ASSOCIATE OHEADL AND OHEAD2 WITH 
BODY AND BODY2. ¥*/ 

Dl = ADDR (BODYL); 

D2 = ADOR(BODY2)5 

/* ASSIGN BODY! AND OHEADI TO 800Y2 
AND OHEAD2. */ 

KHODY2 = BODYIL:; 

OHEAD2 = OHEADLS 


END_MOVE_RL: 


END 


Figure SK3-1. A subroutine procedure that assign 


CONSTANTS IN L_B0DV2: 


NEWMOVE 
MOVE_RL5 MOVE _RE 
MOVE_RE 

END = 
: ROVE _RL 
T_ROVE_AL: HOVE RE 


s a relocatable 





data list to another area 


Because areas LIST BODY1 and LIST_BODY2 have the 
automatic storage class and not the based storage class, 
based areas DUMMY 1 and DUMMY72 are used to associate 
offset variables LIST OHEAD1 and LIST _OHEAD2 with 
LIST_BODY1 and LIST_ BODY?2. 


5K4. Converting Data Lists to and from Relocatable 
Form 


Although the previous discussions have shown how to 
assign relocatable data lists from one area to another, they 
have not shown how to create a relocatable list. The tech- 
niques developed in Chapter 4 for creating data lists dealt 
solely with lists in absolute form and did not consider the 
construction of relocatable lists. One way of creating a 
relocatable list is to convert an established absolute list to 
relocatable form. Subroutine procedure CONV_ AR in 
Figure 5K4-1 shows how this conversion can be made. 
CONV_AR uses four parameters: BODY 1, HEAD, 
BODY 2, and OHEAD. BODY 1 represents the area that 
contains the absolute data list to be converted to reloca- 
table form and assigned to area BODY2. Pointer HEAD 
specifies the address of the first list component in BODY 1, 
and offset OHEAD receives the relative address of the first 


list component in BODY?2 after the list has been converted. 


If the extent of BODY2 is not large enough to accept the 
contents of BODY1, OHEAD receives a null offset value. 
BODY 1 and BODY? can be of any storage class, but stor- 
age is assumed to have been allocated for the correspond- 
ing area arguments upon entry to the subroutine. The 
offset argument corresponding to OHEAD must be de- 
clared relative (either directly or through a dummy based 
area) to the area argument associated with BODY2. Exe- 
cution of CONV_AR does not change the contents of 
BODY 1. 

It is also possible to convert a relocatable. data list to 
absolute form, as shown by subroutine procedure CONV _ 
RA in Figure 5K4-2. Again, this subroutine uses four 
parameters: BODY1, OHEAD, BODY2, and HEAD. 
BODY | represents the area that contains the relocatable 
data list to be converted to absolute form and assigned to 
BODY2. Offset OHEAD specifies the relative address of 
the first list component in BODY1, and pointer HEAD 
receives the absolute address of the first list component in 
BODY 2 after the list has been converted. If the extent of 
BODY? is not large enough to accept the contents of 
BODY 1, HEAD receives a null pointer value. Execution of 
CONV_RA does not change the contents of BODY 1, and 
the same restrictions apply to the parameters of CONV __ 
RA as they.do to CONV_ AR in Figure 5K4-1. A later 
discussion in paragraph 5K6 under “External Relocation” 
shows how relocatable data lists can be constructed di- 
rectly without being converted from absolute form. 


TUCONV_RA? 

T_CONV_AR: 

PROCEDURE OPTIONS (MAIND? 

DECLARE 
.(B00V_1,- BUOY_2) AREA (500), 
OUMMY_BUDY BASED (DUMMY_POINTER) AREA, 
(LLHEAD., Q) POINTER, 
L_OHEAO OFFSET (DUMMY_BODY), 
1 LIST BASED (P), 
2 KEY CHARACTER (3), 
2 DATA CHARACTER (7), 
2 L POINTER, 
CONV_AR ENTRY (AREA (500), POINTER, 
AREA (500), OFFSET (DUMMY, BODY)). 
CONV_RA ENTRY (AREA (500). OFFSET 
(OUMMY_BODY), AREA (500), POINTER): 


P = NULLS 
ALLOCATE LIST IN (B00V_i) SET (PDS 
L_MEAD, O = P§ 
P—>KEY = °§444%: P~>DATA = “CONVERT ®§ 
00 

I= 1 TO 43% 
ALLOCATE. LIST IN (BNOV_1) SET (P)5 
P=>KEY = §222°5 P->DATA = *TREVNOC®? 
Q-> tL = PE Q 3 Ps 

END; 
Q-> L = NULLS 
OUMMY_POINTER © ADDR (B0DY_2); 
bODY_2 = EMPTY; LLOHEAD = NULLO? 


CALL CONV_AR 
(BODY_1, L_HEAD, BODY_2+- L_OGHEAD); 


CONV_AR: 


PROCEDURE 
(BODY1, HEAD, BODY2, OHEAD); 

DECLARE | 

(BODY1, BODY2) AREA (#), 

DUMMY_BODY BASED 

(DUMMY_POINTER) AREA, 

(HEAD, SAVE) POINTER,. 

OHEAD OFFSET (DUMMY_BODY), 

COMPONENTI BASED (C1), 

KEY CHARACTER (3), 

DATA CHARACTER (7), 

L POINTER, 

COMPONENT2 BASED (C2), 

KEY CHARACTER (3), 

DATA CHARACTER (7), 

OL OFFSET (DUMMY_BODY); 


NON AO & RO RD AD 


/* IF AREA CONDITION OCCURS, BODY2 IS 
TOO SMALL TO RECEIVE CONTENT OF © 
BNDOY1L. GN TO NULL_LLIST. */ 
ON AREA 
GO TO 
NULL_LIST$ 
/* IF LIST IN BODY CONTAINS NO 
COMPONENTS, GO TO NULL_LIST. ¥*/ 
IF 
HEAD = NULL 
THEN 
GO TO 
NULL_LIST$ 
/* ASSOCIATE OFFSET VARIABLES OHEAD 
AND OL WITH 800Y2. */ 
DUMMY_POINTER = ADDR(BODY2)3 


/* ALLOCATE COMPONENT2 IN BODY2, 
AND ASSIGN TQ THE ALLOCATION THE 
KEY AND DATA VALUES OF THE FIRST 
LIST COMPONENT IN BODYL. ¥*/ 
ALLOCATE COMPONENT2 IN (BODY2?r 

SET (C2)35 

OHEAD, SAVE = C2; 

C2->COMPONENT2 = HEAD~>COMPONENTI » 
BY NAME; 


Figures 5K4-1 (CONV_AR) and 5K4-2 (CONV_RA). Conversion 
of a data list from absolute to relocatable, and from 
relocatable to absolute 
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/* PERFORM SUCCESSIVE ALLOCATIONS 

OF COMPONENT2 IN BODY2, AND ASSIGN . 
TO THE ALLOCATIONS THE KEY ANDO DATA 
VALUES OF SUCCESSIVE LIST COMPONENTS 
IN BODY1. */ 

Cl = HEAD—O>L; 


DO 
WHILE (C1+=NULL)$ 
ALLOCATE COMPONENT2 IN (BODY2) 
SET (C2)3 
SAVE->OL, SAVE = C23 | 
(C2—>COMPONENT2 = C1->COMPONENT1> 
BY NAME; 
Cl = Cl->L3 
=ND$ 
/* ASSIGN A NULL OFFSET VALUE TO THE 
OFFSET VARIABLE OL IN THE LAST 
COMPONENT OF BODY2e THEN RETURN. */ 
SAVE->OL = NULLO; 
RETURN; - 
/* IF THIS POINT IS REACHED, ASSIGN 
A NULL OFFSET TO OHEAD. */ 
NULL_LIST? 
OHEAD = NULLO3 
END 
CONV_AR: 


IF ; 
LLOHEAD = NULLO 
THEN 
EXIT; _ . 
/* PREPARE TO INVOKE CONV_RA */ 
sODY_1 = BODY_2; 
DUMMY_POINTER = ADOR (BODY1)3 
BODY_2 = EMPTY; L_HEAD = NULL; 


CALL CONV_RA “ 
(BOOY_1»5 L_LOHEAD, BODY 2» L_HEAD); 


CONV_RA: 


PROCEDURE 
(BODYL, OHEAD, BODY2, HEAD); 
DECLARE | | 
(BOOY1L, BODY2) AREA (#), | 
DUMMY_BODY BASED (OUMMY_POINTER) 
AREA, 
.. OHEAD OFFSET (OUMMY_BODY), 
(HEAD, SAVE, TEMP) POINTER, 
COMPONENT1L BASED (Cl), 
KEY CHARACTER (3)>5 
DATA CHARACTER (7). 
OL OFFSET (DUMMY_BODY), 
COMPONENT2 BASED (C2), 
KEY CHARACTER (3), 
DATA CHARACTER (7)s 
L POINTERS . 
/* IF AREA CONOITION OCCURS, BODY2 
IS TOO SMALL TO RECEIVE CONTENTS OF 
BODY1. GO TO NULL LIST. */ 
ON. AREA | 
GO TO 
NULL_LIST3$ 


NN N&R ND 


/* IF LIST IN BODY] CONTAINS NO 
COMPONENTS, GO TO NULL_LIST. #/ 


OHEAD = NULLO 


NULL_LLISTS$ 


/* ASSOCIATE OFFSET VARIABLES OHEAD 
AND OL WITH BODY1. */ 

DUMMY_POINTER = ADDR(BODY1); 

/* ALLOCATE COMPONENT2 IN BODY2, 

AND ASSIGN TO THE ALLOCATION THE KEY 
AND DATA VALUES OF THE FIRST LIST 
COMPONENT IN BODY1L. */ 

ALLOCATE COMPONENT 2 IN (BODY2) 


SET (C203 
HEAD, SAVE = C2; 
TEMP = OHEAD; 
C2->COMPONENT2 = TEMP—>COMPONENT1, 
BY NAME; 
/* PERFORM SUCCESSIVE ALLOCATIONS 
OF COMPONENT2 IN BODY2, AND ASSIGN 
TO THE ALLOCATIONS THE KEY AND DATA 
VALUES OF SUCCESSIVE LIST COMPONENTS 
‘IN BODYL. */ 
Cl = TEMP->OL; 
pO 
WHILE (C1-=NULL) 3 
ALLOCATE COMPONENT2 IN (BODY2) 
SET (C2)3 
SAVE->L, SAVE = C2; 
C2—>COMPONENT2 = C1—>COMPONENTL, 
BY NAME; 
IF 
C1->OL = NULLO 
THEN 
Ch = NULL; 
ELSE | 
Cl = Cl -> OL; 
END; 
/* ASSIGN A NULL VALUE TO THE 
POINTER VARIABLE L IN THE LAST 
COMPONENT OF BODY2, THEN RETURN. */ 
SAVE—>L = NULL; 
RETURN; 
/* IF THIS POINT IS REACHED, ASSIGN 
A NULL VALUE TO POINTER HEAD. */ 
NULL_LIST: 
HEAD = NULLS; 
END 
CONV_RA; 


OUTPUT: 
PUT 
SKIP LIST C*CONTENT OF BODY_2:°)3 
Q = L_HEAD: 
00 
WHILE (Q -~2 NULL)$ 
PUT 
SKIP EDIT (Q —-> KEY, Q —> DATA) 
(Ap XC3)D, ADdS 
Q2#Q-> Li 
END; 
ENO 
T_CONV_RAS 


CONTENT OF BODY_2: 
444 CONVERT 
222 TREVNOC 
222 TREVNOC 
222 TRE VNOC 
222 TRE VNOC 


Figures 5K 4-1 and 5K4-2. (Continued from preceding page) 


76 


5K5. Sorting Relocatable Data Lists 


Once a list has been converted to relocatable form, the list 
need not be converted back to absolute form before it can 
be processed. Processing operations can be applied direct- 
ly to relocatable lists. As an example, consider subroutine 
procedure SORTIS in Figure 5K5-1, which shows how a 
relocatable list of structures can be sorted. SORT15 uses 
two parameters: LIST_OHEAD and LIST_BODY. 

LIST _OHEAD is an offset variable that specifies the loca- 
tion of the first list component in area LIST BODY. As 
usual, LIST BODY can be of any storage class. The sub- 
routine uses the same transposition technique employed 
in previous chapters and is similar to subroutine SORT 11. 


SORTLS: 


PROCEDURE 
(LIST_OHEAD, LIST_BODY); 
DECLARE 
(HEAD,s Te Us V) POINTER, 
LIST_OHEAD OFFSET (DUMMY_BODY), 
LIST_BODY AREA (*), 
DUMMY_BODY AREA BASED 
(OUMMY_POINTER) >» 
1 COMPONENT BASEO (C)> 
2 KEY CHARACTER (3), 
2 DATA CHARACTER (77), 
2 OL OFFSET (DUMMY_BODY)>; 
/* ASSOCIATE OFFSET VARIABLES 
LIST_OHEAD AND OL WITH LIST_8ODY. */ 
OUMMY_POINTER = ADDR(LIST_BODY):; 
/* ASSIGN ADDRESS OF FIRST LIST 
COMPONENT TO POINTER HEAD. ¥*/ 
IF 
LIST_OHEAD = NULLO 
THEN 
HEAD = NULL; 
ELSE 
HEAD = LIST_OHEAD; 
/* IF LIST CONTAINS LESS THAN TWO 
COMPUNENTS, NO SORT REQUIRED. */ 
IF 
(HEAD = NULL) | (HEAD—->OL = NULLO)?. 
THEN 
RETURNS 
/* SORT LIST. */ 
SORT: 
K = O03: 
/* ASSIGN ADORESS OF SECOND 
COMPONENT IN SEQUENCE TO POINTER C.*/ 
C = HEAD->OL>$ 
/* COMPARE KEY FIELNS OF SUCCESSIVE 
COMPONENTS AND PERFORM NECESSARY 
TRANSPOSITIONS. */ 
IF ; 


(HEAU->KEY) > (C->KEY) 


THEN 
DOs 
Lf 
C->0L = NULLO 
THEN 
YT = NULLS 
FLSE 
T = C->OLS 


C->0L = HEADS 
IF 
T = NULL 


Both subroutines use the same structure organization for 
the list components. The number of list components con- 
tained in LIST_ BODY is arbitrary and can even be zero. 

Because an offset variable cannot qualify a based vari- 
able, the offset address must first be converted to a pointer 
address. As SORT15 demonstrates, the address conver- 
sion produces more instructions and generally adds to the 
sort time. The increased sort time, however, may not 
exceed the time required to convert the list back to abso- 
lute form before sorting is performed, and on this basis, a 
relocatable sort may be justified. Ordinarily, though, a list 
should be in absolute form when the list is to be processed 
extensively. 


THEN 
. HFAD->OL 

ELSF 
HEAD->UL = Ts HEAD = C3 K = 15 


NULLOS$ 


END; 


IF 
C->OL = NULLO 
THEN 
T = NULL; 
LLUSEF 
T = C-d>O0LS$ 
DO 
WHILF (Ts=NULL) 5 
LF 
(C->KEY) > (T->KEY) 
THEN 
DUS 
IF 
T->OL = NULLO 
THEN 
Vo= NULLS; 
ELSE 
Vo= F->0L3$ 
T->0L U->OL 5 
U=>UL C->0Ls 


[+ 
V = NULL 
THEN 
C->OL = NULLOS 
ELSE 
C=>0L 
K = l$ 


Vs 


ENDS 

UW = UR>NLs C = U->OL; 

IF 
C->OL = NULLO 

THEN 
T = NULLS 

CLSF 
T 


C->0L3 
END 


IF 
K = 1 

THEN 

GO TO 
SORTS 
/* WHEN LIST IS SORTED, ASSIGN 
ADORESS OF FIRST LIST COMPONENT 
TO LISTLOHEAD. */ 
LISTLOHEAD = HEAD; 
END 

SORT155 


Figure 5K5-1. A subroutine procedure that sorts a relocatable list of structures 
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5K6. External Relocation 


Although it is more convenient to assign a data list to an- 
other area when the list is in relocatable rather than abso- 
lute form, the major advantage of a relocatable list is that 
the list can be stored, without reorganization, on an exter- 
nal storage medium, such as magnetic tape or disk, from 
which it can be retrieved for later processing. 

It is possible, however, to disassembie the components 
of a data list and to write them into a file in unlinked 
form. It is also possible to read the components back into 
internal storage and to reassemble the list by properly 
linking the components. But converting a list to and from 
unlinked form can be costly in execution time, particularly 
with list organizations that are far more intricately con- 
structed than the simple linear lists discussed in this text. 
With relocatable lists, external transmission can be direct 
and, hence, generally more efficient in execution time. 

The following discussions show how relocatable data 
lists are transmitted to and from a file and how such trans- 
mission permits a file of relocatable lists to be sorted and 
printed. 


5K6A. Writing Relocatable Data Lists 


Because stream-oriented input and output statements can- 
not transmit the address values of locator variables, record- 
oriented statements must be used to transmit relocatable 
lists. Output transmission of a list is performed by the 
LOCATE statement. This statement was discussed briefly 
in Chapter 3, and has the following form: 


LOCATE based-variable FILE (file-name) SET (element- 
pointer-variable); 


The LOCATE statement processes sequential, buffered 
files and allocates within an output buffer for the file the 
next available storage area for the specified based variable. 
The location of the allocated storage is assigned to the 
element-pointer variable given in the SET option. The, 
LOCATE statement, however, need not contain a SET 
option; when it does not, an implied SET is assumed, 
which uses the pointer variable in the BASED attribute of 
the specified based variable. When the buffer is filled, its 
contents are automatically transmitted to the associated 
file. The buffer then becomes available again for further 
transmission. 

Subroutine procedure LWRITE in Figure 5K6A-1 shows 
how the LOCATE statement can be used to transmit a 
relocatable data list to a file. The subroutine uses four 
parameters: OUTFILE, LIST_OHEAD, LIST_BODY, and 
BODY_SIZE. OUTFILE is a sequential, buffered output- 
file used for record-oriented transmission. LIST _OHEAD 
is an offset variable that specifies the relative address of 
the first list component in area LIST_ BODY, which can 
contain an arbitrary number of list components. BODY _ 
SIZE specifies the number of bytes in LIST_BODY. 


78 


LWRITE: 

PROCEDURE 

(OUTFILE, LIST_OHEAD, 

LIST_BODY, BODY_SIZE)3 

DECLARE 
| DUMMY_BODYL AREA BASED 
(DUMMY_POINTERL), 

UUMMY_BODY2 AREA BASED 
(NUMMY_POINTER2). 

LIST_OHEAD OFFSET (DUMMY_BODY1), 

LIST_BODY AREA (BOODY_SIZE}), 

BOOY_SIZE FIXED DECIMAL (5), 

BEN_SIZE FIXED BINARY (15,0), 

OUTFILE FILE RECORD OUTPUT, 

1 DUTRECORD BASED (OUTPOINTER), 

2 B.SIZE FIXED BINARY (15,0), 

2 OHEAD OFFSET (OUMMY_BODY2), 

2 BUOY AREA (BIN _SIZF REFER (B_SIZE)): 


4* INITIALIZE SIZE OF BODY IN 
OUTRECORD. */ 
BIN_SIZE = BODY_SIZE; 


/* LOCATE STORAGE IN OUTPUT BUFFER 
FOR OUTRECORD, AND ASSIGN LOCATION 
TO OUTPOINTER. */ 

LOCATE OUTRECORD FILE (OUTFILE) SET 
(OUTPOINTER); 


/* ASSOCIATE OFFSET VARIABLE OHEAD 
WITH LOCATION OF OUTRECORD IN 
OUTPUT BUFFER. */ 

DUMMY_POINTER2 = OUTPOINTER: 


/@ ASSOCIATE OFFSET PARAMETER 
LISTLOHEAD WITH LIST_B80DY. 4/ 
DUMMY_POINTERL = ADORILIST BODY); 


4* ASSIGN LISTLOHEAD AND LIST BODY 
TO OUTRECORD. ¥/ 
OUTPOINTER-SOHEAD = LIST_OHEAD: 
OUTPOINTER=SB0DY = LIST BODY; 

ENO 
LWRITES 


Figure 5K6A-1. A subroutine procedure that writes a relocatable 
data list into a file 


Execution of LWRITE causes storage in the output 
buffer to be allocated for the self-defining based structure 
OUTRECORD, which contains the fixed binary variable 
B_ SIZE, the offset variable OHEAD, and the area variable 
BODY. The variable B_ SIZE represents the size of 
BODY, which is declared with the REFER option. The 
values of LIST_OHEAD and LIST_BODY are then as- 


_ signed to OHEAD and BODY, which are eventually writ- 


ten along with B_ SIZE as a self-defining logical record in 
OUTFILE when the output buffer becomes full. 

Because LIST_BODY can have any storage class, the 
OFFSET attribute of LIST_OQHEAD, which requires a 
based area, uses based area DUMMY BODY1. Assignment 
of the address of LIST BODY to the pointer variable 
DUMMY _POINTER1, which is associated with DUMMY _ 
BODY 1, causes LIST OHEAD to become relative to 
LIST _BODY. 


When the LOCATE statement allocates storage for 
OUTRECORD, the location of the storage in the output 
buffer is assigned to the pointer variable OUTPOINTER. 
Assignment of OUTPOINTER, in turn, to DUMMY _ 
POINTER2, which is associated with DUMMY _ BODY 2, 
causes OHEAD to become relative to the location of 
OUTRECORD in the output buffer. Note that assignment 
of LIST OHEAD to OHEAD produces no address modi- 
fication, because both variables are offset variables. As 
usual, list components maintain their relative positions 
when assigned from LIST_ BODY to BODY. 

Environmental information, such as input/output de- 
vice type, unit number, recording density, block size, and 
record size, is not specified in an ENVIRONMENT attri- 
bute for OUTFILE. Data Definition (DD) statements are 
assumed to contain such information in the job step that 
calls for execution of the program under the operating 
system. 


LOUT1L: 


PROCEDURE OPTIONS (MAIN); 

DECLARE 

CARD, 

KEY CHARACTER (3)¢ 

DATA CHARACTER (77)¢ 

COMPONENT BASED (CUMPONENT_POINTER), 
KEY CHARACTER (3), 

DATA CHARACTER (77)> 

OL OFFSET (OUMMY_BODY), 

QUTRECORD BASED (OUTPOINTER), 

BLSIZE FIXED BINARY (1550), 

OHEAD OFFSET (DUMMY_8O0DY), 

BODY AREA (BIN_SIZE REFER(B_SIZE)), 
BIN_SIZE FIXED BINARY (15), 

DUMMY_BODY AREA BASED (DUMMY_POINTER), 
WORK_AREA AREA (550), 

LAST POINTER, 

OUTFILE FILE RECORD OUTPUT, 

LWRITE ENTRY (FILE, OFFSET 
(DUMMY_BUDY), AREA (*), FIXED (5))3 


NA AO em AD AD RO mm AD PR ee 


/* ESTABLISH ENDFILE 
AND AREA ON-CONOITIONS. */ 
ON ENDFILE (SYSIN) 
GO TU 
PROC_END; 
ON AREA 
BEGIN; 
PUT 
LIST C* INSUFFICIENT STORAGE °)5 
CLOSE FILE ( 
SYSPRINT)$ 
GO TO 
PROC_END; 
ENO; 


/*®INITIALIZE SIZE OF BODY IN OUTRECORD*/ 


BIN_SIZE = 5005 


/*FREE ALL ALLOCATIONS IN WORK_AREA, 
AND ALLOCATE STORAGE FOR OUTRECORD 
IN WORK_AREA. */ 

START: 
WORK_AREA = EMPTY; 
ALLOCATE OUTRECORD IN (WORK_AREA) 
SET (OUTPOINTER)$ 


When the record size of OUTRECORD is specified in a 
DD statement, the record size must account for the storage 
associated with B_ SIZE, OHEAD, and BODY. The 
length, rather than the size, of BODY must be used (see 
the previous discussion in this chapter under “The Length 
of an Area”, paragraph 5G). As stated earlier, the length 
of an area written as a record includes the number of bytes 
used for area control information as well as the size of the 
area. 


5K6B. An Example that Creates Reliocatabie Data Lists in 
a Work Area and Writes Them into a F ile 


An application of the previously discussed subroutine 
LWRITE appears in program LOUT1 of Figure 5K6B-1, 
which shows how relocatable data lists can be created di- 
rectly, rather than converted from absolute to relocatable 
form, and then written into a file. 


/*ASSOCIATE OFFSET VARIABLE OL AND 
OHEAD WITH BODY IN WORK_AREA, */ 
DUMMY_POINTER = ADOR (OUTPOINTER 
-> BODY); 


/*¥INITIALIZE THE POINTER *LAST@¢/ 
LAST = NULL? 


/* OBTAIN FIVE INPUT CARDS, AND 
ASSIGN EACH TO COMPONENT STORAGE 
ALLOCATED AND LINKED IN BODY WITHIN 
WORK_AREA. */ 
DO 
I = 1 TO 53 
ALLOCATE COMPONENT IN (OUTPOINTER 
-> BODY) SET (COMPONENT _ POINTERS 3 
GET : 
EDIT (CARD) (AC3D, ALTIIDS 
COMPONENT POINTER ~-> COMPONENT = 
CARD, BY NAMES 

IF 
LAST = NULL 

THEN 
UUTPOINTER -—> GHEAD = 
COMPONENT POINTERS 

ELSE 
LAST => OL = COMPONENT POINTERS | 
LAST = COMPONENT POINTERS 


tNO$ 
J*ASSIGN NULL OFFSET TO OL ITN LAST 
reictglenh aay 
LAST => OL © NULLOS? 
/*WRITE OHEAD AND BODY INTO OUTFILE*/ 
CALL 
LWRITE (OUTFILE, OQHEAD, BODY, SO00)% 
/*® PROCESS NEXT FIVE INPUT CARDS ,*/ 
GU TQ) | 
START 3 
PROC_END: 


CLOSE FILE ( 
QUTFILE}§ 
END 
LOUTI; 


Figure SK6B-1. Creating relocatable data lists in a work area and writing them into a file 
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LOUT 1 reads five cards from the standard system input 
file SYSIN, assigns each card to a relocatable list compo- 
nent allocated and linked in the area BODY. Offset 


_ OHEAD specifies the relative address of the first list com- 
ponent in BODY. Both OHEAD and BODY form ele- 
ments of the self-defining based structure OUTRECORD, 
which is allocated in the work area WORK AREA. The 
variable B_SIZE represents the size of BODY, which is 
declared with the REFER option. Subroutine LWRITE 
then writes OHEAD and BODY as a record into the out- 
put file OUTFILE, and processing continues with the next 
five input cards. 


LOUT2: 


PROCEDURE OPTIONS (MAIN); 
DECLARE 
CARD, 
KEY CHARACTER (3), 
DATA CHARACTER (77), 
COMPONENT BASED (COMPONENT_POINTER), 
KEY CHARACTER (3), 
DATA CHARACTER (77), 
OL OFFSET (DUMMY_BODY), 
OUT_RECORD BASED (OUTPOINTER), 
OHEAD OFFSET (DUMMY_BODY), 
BODY AREA (500), 
DUMMY_BODY AREA BASED 
(DUMMY” POINTER), 
LAST POINTER, 
OUTFILE FILE RECORD OUTPUT; 
/* ESTABLISH ENDFILE AND AREA 
UN-CONDITIONS. */ 
ON ENDFILE (SYSIN) 
GO TO 
END_LOUT2; 
UN AREA 


NO RS we RO AD RO ee RO RO me 


BEGIN; 
PUT 
LIST (* INSUFFICIENT STORAGE*);3 
CLOSE FILF ( 
SYSPRINT)3$ 
GO TO 
END_LOUT23 
tND3$ 
/* GET FIRST INPUT CARD IN NEXT SET 
OF FIVE BEFORE LOCATING STORAGE 
FOR OUT_RECORD IN OUTFILE BUFFER. 
THIS STEP DETECTS END-OF-FILE 
CONDITION BEFORE LOCATING 
UNNECESSARY STORAGE IN BUFFER. */ 
START: . 
GET 
EDIT (CARD) (A(3), AUT7))3 
LOCATE OUT_RECORD FILE(OUTFILE) 
SET (OUTPOINTER)3 
4*® ASSOCIATE OFFSET VARIABLES OL 
AND UHEAD WITH BODY IN OUTFILE 
BUFFER. */ 
DUMMY_POINTER = 
ADDR (OUTPOINTER->BODY) ; 


5K6C. An Example that Creates Relocatable Data Lists in 
an Output Buffer and Writes them into a File 


_ The use of a work area in the previous program LOUT]1 is 


not necessary, because no processing is performed on the 
relocatable lists created in the work area. Instead, the lists 
can be generated directly in an output buffer, as shown by 
program LOUT2 in Figure 5K6C-1. LOUT2 produces the 
same results as LOUT1 but replaces subroutine LWRITE 
with a LOCATE statement that allocates list storage di- 
rectly in the output buffer associated with the file OUT- 
FILE. Also, the records generated by LOUT2 are not self- 
defining, as they are in LOUT1. ‘The data definition state- 
ment for LOUT1 records specify four more bytes than are 
specified for LOUT2. The extra four bytes are occupied 
by the offset variable contained in LOUT1 records. Such’ 
specifications relate to the implementation in use. 


/* ALLOCATE COMPGNENT STORAGE FOR 
FIRST CARD IN BODY WITHIN OUTFILE 
HUFFER. */ 

ALLOCATE COMPONENT IN 
(OUTPOINTER-—>BODY) 

SET (COMPONENT_POINTER); 

/* ASSIGN FIRST CARD TO COMPONENT 
STORAGE. */ 


COMPONENT_POINTER~SCOMPONENT = 
CARD, BY NAME; 
/* ASSIGN ADORESS OF FIRST COMPONENT 
TO OUTPOINTER->OHEAD. */ 
OQUTPOINTER—>OHEAD = 
COMPONENT_POINTERS 
/* SAVE ADDRESS OF COMPONENT IN WORK 
POINTER LAST. */ 
LAST = COMPONENT_POINTER; 
/* ASSIGN REMAINING FOUR CARDS OF 
INPUT SET TO COMPONENT STORAGE 
ALLOCATED AND LINKED IN BODY 
WITHIN OUTFILE BUFFER. ¥*/ 
bO 
I = 1 T0 4% 
ALLOCATE COMPONENT IN 
(OUTPOINTER->BODY) 
SET (COMPONENT_POINTER)$ 
GET . 

FDIT (CARD) (A03)5 AUTTIDS 
COMPUNENT_POINTER=>COMPONENT = 
CARD, BY NAMES : 
LAST->OL = COMPONENT_POINTER; 
LAST = COMPONENT_POINTERS 

END; j 
/* ASSIGN NULLO OFFSET TO Ot IN 
LAST COMPONENT. */ 
LAST->UL = NULLO; 
/* PROCESS NEXT FIVE INPUT CARDS. */ 

GO TO 

STARTS 

END_LOUT 2: 

CLOSE FILE ( 

: OUTFILE)$ 

ENO 
LOUT2; 


Figure 5K6C-1. Creating relocatable data lists in an output buffer and writing them into a file 
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5K6D. Reading Relocatable Data Lists 


Once relocatable lists are written into a file, they become 
available for further processing at a later time. Retrieval 
of a relocatable list from a file is achieved with the READ 
statement, whfch was discussed briefly in Chapter 3 and 
has the following form: 


READ FILE (file-name) SET (element-pointer-variable); 


The READ statement obtains the location of the next 
logical record in a buffer associated with the specified 

file and assigns the location to the element-pointer variable 
given in the SET option. A based variable associated with 
the same pointer will then relate to the fields of the logi- 
cal record. The based variable is effectively overlaid on 
the logical record in the buffer. 

Subroutine LREAD in Figure 5K6D-1 shows how a 
READ statement can be used to obtain the location of the 
next logical record in an input buffer. LREAD uses two 
parameters: INFILE and INPOINTER. INFILE isa 
sequential, buffered input-file used for record-oriented 
transmission. INPOINTER is a pointer variable that re- 
ceives the address of the next logical record in the buffer 


associated with INFILE. When all records have been read 
from INFILE, execution of LREAD causes INPOINTER 
to receive a null pointer value. 


5K6E. An Example that Sorts and Prints Relocatable 
Data Lists Contained in a File 


An application of the previously discussed subroutine 
LREAD appears in program SORT 16 of Figure SK6E-1, 
which shows how relocatable data lists can be retrieved 
from a file and how the components of the retrieved list 
can be sorted and printed. Sorting is performed by sub- 
routine SORT15, which was discussed previously. 
Procedure SORT16 contains a declaration for B_ SIZE 
which is contained in the self-defining records written by 
LOUT1. The declaration for B_ SIZE is not used in 
SORT16 for reading records written by LOUT2. 
LREAD: 
PROCEDURE (INFILE, 
DECLARE 


INFILE FILE RECORD INPUT, 
INPOINTER POINTERS . 


INPOINTER); 


/* AT END OF INFILE, 
SET INPOINTER TO NULL, 
AND ALLOW NORMAL: RETURN FROM 
ON-UNIT TO TERMINATE 
SUBROUTINE #/ 
ON ENDFILE CINFILE) 
INPOINTER = NULL? 


/* READ NEXT LOGICAL RECORD FROM INFILE, 
AND SET INPOINTER TO LOCATION 
OF RECORD IN INPUT BUFFER */ 
READ FILE (INFILE) SET (INPOINTER)3 
END 
LREAD; 
Figure 5K6D-1. A subroutine that reads a relocatable data list 
from a file 


SORT16: 


PROCEDURE OPTIONS 
DECLARE 
INFILE FILE RECORD INPUT, 
INRECORD BASED (INPOINTER), 
B_SIZE FIXED BINARY, 
QOHEAD OFFSET (OUMMY_BODY), 
BODY AREA (500), 
COMPONENT BASED 
(COMPONENT_POINTER), 
2 KEY CHARACTER (3), 
2 DATA CHARACTER (77), 
2 OL OFFSET (DUMMY_BODY), 
DUMMY_BODY AREA BASFD 
(DUMMY_POINTER), 
LREAD ENTRY (FILE, POINTER), 
SORT15 ENTRY (OFFSET(OUMMY_BODY) , 
AREA(500))3 
/* READ NEXT RELOCATABLE LIST FROM 
INFILE, AND ASSIGN LIST LOCATION TO 
INPOINTER. */ 


(MAIN); 


pm NON A ew 


START: 
CALL 
- LREAO CINFILE, INPOINTER)$ 
/* ITF INPOINTER IS NULL», END OF 
INFILE REACHED. GO TO END OF 
PROGRAM. ¥*/ 
IF 
INPOINTER = NULL 
THEN 
GO TO 
END_SORT163 
/* ASSOCIATE OFFSET VARIABLES 
OHEAD AND OL WITH BODY OF LIST. */ 
DUMMY_POINTER = 
ADDR( INPOINTER—>BODY) $ 
/* SORT LIST. */ 
CALL 
SORTLS(INPOINTER->OHEAD, 
INPOINTER~>BODY) $ 
/* PRINT CONTENT OF SORTED LIST. */ 
IF 
INPOINTER=>OHEAD = NULLO 

THEN 
COMPONENT_POINTER = NULL; 

ELSE 
COMPONENT_POINTER = 
INPOINTER—>OHEADS 

DO 
WHILE (COMPONENT_POINTER-~=NULL ) $ 

PUT 
EDIT (COMPONENT_POINTER-D>KEY, 
COMPONENT_POINTER—>DATA) 
(COLUMN(1), A(3), ACT7T))$ 

IF 
COMPONENT_POINTER=—->OL = NULLO 

THEN 
COMPONENT_POINTER = NULL? 

ELSE : 
COMPONENT_POINTER = 
COMPONENT_POINTER—DOL 3 

END; 
PUT 
SKIP (2); 
/* PROCESS NEXT RELOCATABLE DATA 
LIST. */ 
GO TO 
STARTS 


END_SORT16: 

CLOSE FILE ( 
SYSPRINT)3 

END 
SORT163 


Figure SK6E-1. Sorting and printing relocatable data lists 
contained in a file 
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SL. REVIEW OF TECHNIQUES FOR CREATING 
RELOCATABLE DATA LISTS 


This chapter has shown how to organize a data list in re- 
locatable form so that it can be moved conveniently from 
one location-to another. The chief reason for considering 
the relocation of a data list occurs when the list is written 
into a file; subsequent processing of the list requires that 

it be retrieved from the file and assigned to an area in main 
storage. Since this storage area generally differs from the 
area that originally contained the list, the values of the 
pointer variables that link the components of the list be- 
come invalid in the new area. 

One way of maintaining proper linkage is to reconstruct 
the list, component by component, in the new area. But 
this method is costly in execution time, particularly when 
frequent movement of the list is required. A more effi- 
cient way is to treat the list as a unit and assign its contain- 
ing area to the new area. The list, however, will not be 
linked properly in the new area; the area assignment will 
have invalidated the pointer values within the transmitted 
list. Even if the pointers were to remain unchanged, they 
would still refer to the components of the list in the 
original area and not to the components in thenew area. 
This difficulty is overcome by using offset variables rather 
than pointer variables to link the components of the list. 

Figure 5L-1 contains illustrations of a data list linked 
by pointer variables (absolute form) and by offset variables 
(relocatable form). The offset head OHEAD and the off- 
set links OL in the relocatable list contain the relative ad- . 
dresses of list components. These addresses are relative to 
the beginning of the containing area. They remain valid 
when the relocatable list is assigned to another area be- 
cause the components of the list retain their same relative 
positions within the new area. 

Since most lists are initially constructed in absolute 
form, relocatable lists are conveniently obtained by con- 
verting from absolute to relocatable form. Subroutine 
CONV_AR showed how this conversion may be per- 
formed. Similarly, subroutine CONV_RA demonstrated 
the reverse conversion (relocatable to absolute form). 

The. essential techniques used by both of these sub- 
routines are illustrated in Figure 5L-2, which shows how 
area assignment may be used to relocate a data item and 
how the location of the item may be obtained in the 
assigned area. The figure assumes that offset variable Ol 
has been declared with the attribute OFFSET(AREA]1) 
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and that offset variable O2 has been declared with the 
attribute OFFSET(AREA2). These attributes cause all 
address values of O1 to be made relative to the beginning 
of AREA] and those of O2 to be made relative to the be- 
ginning of AREA2. For illustration purposes, the figure 
assumes the arbitrary addresses 2000 and 4025 for __ 
AREAI and AREA2. 
It is also assumed that storage has been allocated for 

the based variable DATA_ITEM at location 2075 within 
Al +> AREAI and that this address has been assigned to 
pointer P1. The address of DATA_ITEM relative to the » 
beginning of Al —> AREA| is obtained by assigning P1 to 
O1. The program automatically subtracts the address 
(2000) of Al —> AREAI from the value (2075) of Pl and 
assigns the difference (75) to O01. When Al —> AREAI is 
assigned to A2 —> AREA2, DATA_ITEM retains its rela- 
tive location (75) within the new area. Note, however, 
that the absolute address of DATA_ITEM in A2 --> 
AREAZ2 is not immediately available. The relative location 
(75) of DATA_ITEM in A2 —> AREA2 must first be’ 
assigned to offset variable O02, which is associated with 
AREAZ, Since the value of an offset variable is not 
changed when it is assigned to another offset variable, OZ 
receives the value 75 when O1 is assigned to 02. The ab- 
solute address of DATA_ITEM in A2 —> AREA2 is then 
obtained by assigning O2 to pointer P2; the address (4025) 
of A2 —> AREAZ2 is automatically added to the value (75) 


of 02, and the sum (4100) is assigned to P1. When the 


subroutines CONV_AR and CONV_RA convert a data 
list to or from relocatable form, they apply these address- 
ing techniques to each component in the list. 

Figure SL-3 shows how area assignment can be used to _ 
move two relocatable lists within a single area. The com- 
ponents of both lists retain their relative positions in the 


_ new area, as illustrated by the sample values of the offset 


links. (Note that the components of each list are arranged 
within the figure in logical sequence and are not scattered 
to show their physical positions in the area.) 

When a relocatable list is written into a file, the 
LOCATE statement is first used to obtain storage for the 
list in an output buffer. Area assignment is then used to 
move the list into the buffer, and, when the buffer be- 
comes full, it is automatically transmitted to the file. In 
turn, retrieval of a relocatable list from a file is achieved 
with a READ statement that contains a SET option. The 
SET option obtains the position of the list in an input 
buffer. 





B1—>BODY!1 





DATA LIST IN ABSOLUTE FORM 


B2 —>BODY2 





DATA LIST IN RELOCATABLE FORM 


Figure 5L-1. A data list in absolute and relocatable form 





Al —>AREA1 A2—>AREA2 
DATA_ITEM — DATALITEM | 

H o 
; 
17 

A2 —> AREA2= A1 —>AREA!1; /* ASSIGN Al —>AREA1 TO A2 —->AREAZ2.*/ 

O1=P1; /* SET O1 TO RELATIVE ADDRESS OF DATA_ITEM IN Al ~—>AREA1.*/ 

O02 = 01; /* SET O2 EQUAL TO 07.*/ 

P2 = 02; /*SET P2 TO ABSOLUTE ADDRESS OF DATA_ITEM IN A2 —>AREA2.*/ 


Figure 5L-2. Obtaining the absolute address of a data item in an assigned area 
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B1—>BODY1 





B2 —> BODY 2 





OL 





B2 —> BODY2 = B1—> BODY1; 
OH2A = OH1A; 
OH2B = OH1B; 


Figure 5L-3. Assigning relocatable data lists to another area 
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5M. SUMMARY OF CHAPTER 5 


A. A list can be treated as a collective unit by referring to 
the area in which the list components have been allo- 
cated; internal and external movement of a list then 
becomes’ possible by transmitting the containing area. 


B. The assignment statement permits the contents of one 
area to be assigned to another area. However, pointer 
values in the assigned area become invalid in the re- 
ceiving area. 


C. No operators can be applied to area variables. 


D. When an area is allocated, it receives the empty state. 
Ani area can also be made empty by assigning it the 
value of an empty area or the value of the built-in func- 
tion EMPTY. 


E. The extent of an area is the number of storage bytes 
between the start of the area and the end of the alloca- 
tion most distant from the start. 


F. Assignment of an area effectively frees all allocations 
in the receiving area, and then assigns the extent of the 
area to the receiving area. 


G. All free-storage gaps within an area are retained during 
area assignment, so that allocations within the assigned 
extent maintain their locations relative to each other. 


H. When the extent of an assigned area exceeds the size of 
the receiving area, an AREA ON-condition occurs, and 
the content of the receiving area becomes undefined. 


I. The length of an area is the sum of the area size (spec- 
ified in the AREA attribute) and the number of storage 


bytes occupied by the area control information, which - 


is supplied by the PL/I compiler. 


J. During record-oriented transmission of an area variable, 
the record length is determined by the length of the 
area, not the size of the area. 


K. An offset variable has a relative address as its value and 
is declared with the OFFSET attribute, which has the 
following form: 


OFFSET (area-variable) 


The area variable in parentheses must be based and un- 
subscripted, and have an implied or explicit level num- 
ber of one. 


L. When the value of a pointer variable is assigned to an 
offset variable, the assigned value is made relative to 
the absolute address of the area specified in the OFF- 


SET attribute for the variable. The address computa- 
tion is equivalent to the following calculation: 


offset value = (pointer value) — (absolute address of 
area) 


M. When an offset variable is assigned to a pointer varia- 
ble, the assigned offset value is converted to a pointer 
value. The offset value is effectively added to the ab- 
solute address of the area specified in the associated 
OFFSET attribute: 


pointer value = (offset value) + (absolute address of 
area) 


N. When an offset variable is assigned to another offset 
variable, the offset value is assigned without modifica- 
tion. 


O. A null offset value is assigned to an offset variable 
through the built-in function NULLO. 


P. A null offset value cannot be assigned to a pointer var- 
iable. Similarly, a null pointer value cannot be assigned 
to an offset variable. 


Q. The comparison operators equal (=) and not equal 
(+=) are the only two operators that can use offset 
variables as operands. 


R. An offset variable cannot qualify a based variable. The 
offset value must first be assigned to a pointer variable, 
which is then used to qualify the based variable. " 


S. The values of locator variables (offsets and pointers) 
cannot be converted to any other type of data, nor can 
any other type of data be converted to locator type. 


T. Locator variables may be used as arguments and para- 
meters. When an offset argument is associated with an 
offset parameter, both must be offset with respect to 
the same area. 


U. A relocatable data list is formed by using offset vari- 
ables rather than pointer variables as component links 
in the list. 


V. Internal relocation of a relocatable data list is achieved 
with the assignment statement; the area that contains 
the list is assigned to another area. 


W. Only record-oriented transmission statements.can be 
used for external relocation of lists. The LOCATE 
statement transmits a list to a file, and the READ state- 
ment retrieves a list from a file. The area that contains 
the list is transmitted to and from the file. 
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Appendix. Summary of List-Processing Facilities 


The following summary divides the list-processing facilities 
into five categories: attributes, built-in functions, ON- 
conditions, statements, and miscellaneous features. Facil- 
ities within each category appear in alphabetic order. 

When used in the format of each facility, brackets [ ] 
denote optional items; braces { } indicate that a choice 
must be’ made from the enclosed items, which are separ- 
ated by an “or” symbol |; and an eilipsis(... ) specifies 
optional repetition of the preceding item. 


Attributes. 
AREA [{ (size-expression)|(*) } | 
BASED (element-pointer-variable) 
OFFSET (area-variable) 
POINTER 


Built-In Functions 
ADDR (argument-variabie) 
EMPTY 
NULL 
NULLO 


On-Condition 
AREA 


Statements 
ALLOCATE based-variable 
_ [IN (area-variable)} 
[SET (pointer-variable)} 
{, based-variable 
[IN (area-variable)] 
[SET (pointer-variable)|] . . .; 
FREE based-variable 
[IN (area-variable)] 
[, based-variable 
[IN (area-variable)]] .. .; 
LOCATE based-variable 
FILE (file-name) 
SET (pointer-variable); 
READ FILE (file-name) 
SET (pointer-variable); 
Miscellaneous Features 
Pointer-qualification symbol: 
—> 
REFER option: 
element-variable REFER (element-variabie) 
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Index 


Figure 
Number 


Absolute addresses 
Absolute list 

ADDR built-in function 
Addressing storage 
ALLOCATE statement 
Area variables 

Arrays 

Arrays of structures 
AREA attribute 
AREA ON-condition 
Assignment of areas 
Assignment of offsets 
Assignment of pointers 


Based storage 
Based variables 
Buffer storage 


Contextual pointers 


Data movement 
DEFINED attribute 


Element items 

EMPTY built-in function 
Extent of an area 
External relocation 


FREE statement 
IN option 


Length of an area 
List organization 
List usage 

LOCATE statement 


NULL built-in function 
NULLO built-in function 


Offset variables 


Pointer arrays 
Pointer qualification 
Pointer variables 
Program examples in 
figure number 
sequence: 


SORT1 2E1-1 


Para- 
graph 


Number 


3D 
4B 
3D2A 
1A 
4A2 
5B 

2B 
2D 
4A6A 
4A6C 
SB 
551 
3D2B 


4A 
3D2 
SK6C 


3E4 


1B 
4A6A 


2A 
SB 
SC 
SK6 


4A3 
4A6B 


5G 
4B 
1D 
SK6A 


3D2A 
5J2 


SJ 


3G 
3E1 
3D2 


Page 
Number 


24 
53 
25 

] 
46 
62 

7 
10 
51 
53 
62 
67 
25 


45 
26 
80 


32 


1 
51 


7 
62 
63 
78 


46 
52 


65 
53 

4 
78 


25 
68 


66 


35 
28 
24 


11 


SORT2 
SORT3 
SORT4 
SORTS 
MEAN 
SWAP 
SORT6 
SORT7 
SORTS 
SORT9 
SORT10 
SORTI1 
SORT 12 
SORT13 
SORT14 
EXTENT 
MOVE_L 
MOVE_ RL 
CONV_AR 
CONV _RA 
SORT15 
LWRITE 
LOUT1 
LOUT2 
LREAD 
SORT16 


READ statement 
REFER option 
Relative addresses 
Relocatable list 
Relocation of data lists 
Restrictions on based 
variables 


SET option 
Size of an area 
Storage 
automatic 
based 
controlled 
Structures 
Symbolic addresses 


Figure 
Number 
2E1-5 
2E2-1 

3C 1-1 
3C2-1 
3D3B-1 
3E2-1 
3F2-1 
3F3-1 
3G1-1 
3G 1-5 
3G2-1 
3G2-7 
4A4-1 
4ASB-1 


4A6D-1 


SF-1 
5K1-3 
SK3-1 
5K4-1 
SK4-2 
SK5-1 
SK6A-1 
SK6B-2 
SK6C-1 
SK6D-1 
SK6E-1 


Para- 
graph 


Page 


Number Number 


SK6D 
4A5A 
3C 
SK2 
SK 


3E3 


4A2 
5c 


4A 
4A 
4A 
2C 
3B 
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